innovaphone wiki - User contributions [en]

Reference14r2:Concept App Platform

2026-05-08T08:04:08Z

Dde: /* It still doesn't start */

= General =
* V13 uses [https://buildroot.org/ buildroot]
* this is an own (innovaphone) collection of packages
* For further information see: [https://buildroot.org/docs.html Buildroot Documentations]

== Requirements ==

* V13 or above
* Gateway (arm): IPx10 (with CF card) or IPx11 (with mSATA SSD)
* Gateway (arm64): IPx13 (with m2 SSD)
* Virtual (x86_64)
** HyperV with [https://docs.microsoft.com/de-de/windows-server/virtualization/hyper-v/deploy/upgrade-virtual-machine-version-in-hyper-v-on-windows-or-windows-server#supported-virtual-machine-configuration-versions VM-configuration Version] 6.2 (minimum: Windows 10 or Windows Server 2016)
** VMWare
** Proxmox/KVM/Qemu

== Default credentials ==

'''During INSTALL, the default passwords are replaced with the global Admin PW!'''
* SSH-Login with '''admin''' and '''ipapps'''
* root login with '''root''' and '''iplinux''' (the root login is not directly possible, you have to login as admin first and use the command ''su root'')
* manager App (web login) '''pwd'''

= App Platform - arm/arm64 (Gateway)=

* The installation image has a size of ~50MB. During installation, the following partitions are created<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 fat32: 200MB (contains ramdisk, rootfs and kernel)
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB

When comparing potential performance of the IPxx11 platform compared to the IPxx10 platform, there are some major differences:
* SSDs found in the xx11 are faster and more reliable than the CF found in the xx10
* the available RAM for the App Platform (as specified in column ''RAM for LAP (GB) out of RAM'' in chapter ''Technical data and recommended number of users supported'' of [[Howto:How to implement large PBXs#Technical data and recommended number of users supported|How to implement large PBXs]]) is factor 6 larger on the xx11 (1,536 GB) than on the xx10 (0,256 GB))
* the xx11 has gigabit Ethernet while the xx10 has 100Mbps Ethernet. The xx10 is therefore not well suited for Apps with larger network traffic, such as Recordings
* the CPU of the xx11 (although it runs on the same frequency) is roughly 20% faster than the xx10

While it is hard to predict the performance of the App Platform in a specific scenario, we see that in a real life environment an App Platform running on an xx11 platform can well support 150 users. The xx10 platform is estimated to support 120 users. Because CPU performance is the limiting factor, larger setups can be built based on the virtual machine platform (see [[#App services and multi-threading|App services and multi-threading]] below).

<references/>

= App Platform - x86-64 (Virtual Machine 64bit) =

* The default disk size is 16GB. It should be increased '''before''' the first start if needed!
* Multiple CPUs are supported, default is one CPU
* default RAM: 512MB
* static IP address, DNS, Gateway can be configured with the command '''setip''' on the console. Run '''setip --help''' to get a list of parameters. (Example: setip --addr=x.x.x.x --mask=x.x.x.x --gateway=x.x.x.x --dns1=x.x.x.x)
* If you have permission problems change to su user (Password is iplinux or your new admin password)
* To figure out your ip address you can use the command: ''ip address'' on the console.
* '''loadkeys de''' can be used to change to german keyboard layout (etc.)
* partitions<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 ext2: 350MB (contains ramdisk, rootfs and kernel)
*** the real partition format size is smaller but there is no need to monitor sda1 as sda1 won't grow during usage of the App Platform
*** sda1 is completely exchanged during an image update and its size might have changed but will never exceed these 350MB
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB
* VMWare Tools: Open VM Tools
* Qemu Guest Agent: installed since 110032
** The qemu guest agent can be configured in Proxmox with ''Virtio'' or ''ISA''. Before version 130012, you must use ISA, as Virtio was not supported with older versions.

<references/>

= Installation =
==ARM Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-armel.img'' image file.
* The installation runs without any further required step.

==ARM64 Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-arm64.img'' image file.
* The installation runs without any further required step.

==Virtual machine==

* Import the image into your server environment.
** Proxmox: follow this description here, just with the app-platform-ova.zip: https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Proxmox_VE
* Edit the disk size, if needed.
* Start the machine and wait until it reboots and starts again.
* Note: If you need to access an IP addresses available through a VPN connection from from inside the virtual machine, it could be that you need to set the network of your VM to NAT (and also add the URL for an IP to /etc/hosts)

[https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Configuration More Configuration Hints regarding VM Ware]

== Backup of the Apps ==

Each App Service can have multiple instances and each instance has its own database. The manager app itself also has its own database. 
There are no other files which need to be backuped. 
The standard way to backup the databases is through the Devices App [[{{NAMESPACE}}:Concept_App_Service_Devices#Backups]]. 
 
An alternate way is to use a command file which is similar to the command files from the firmware.

===Commands===
* '''times''' 0,12 # backup only at 0 or 12 o'clock
* '''backup-instances''' http://user:pw@ip/path/#I-#D.dump PUT
** PUT and POST are supported, all instances including the manager itself are saved
* '''backup-instance''' http://user:pw@ip/path/#I-#D.dump apidemo example.com PUT
** backup a single instance with instance name and instance domain
* '''backup-manager''' http://user:pw@ip/path/#I-#D.dump

===Hash parameters===
* #L App Platform label (neu), e.g. 10024
* #A App label (neu), e.g. 130004
* #I instance name (neu), e.g. reporting1
* #D instance domain (neu), e.g. innovaphone.com
* #m MAC address of the LAP, e.g. 00ab11eeff
* #d Current date and time (plain UTC without daylight saving and timezone adjustments) 20051010-170130
* #bn rolling backup index (n >=0 and <= 9, just one digit)
* ## escapes a hash mark

= App Platform Infrastructure and Concept =
== Webserver ==
The app platform includes a webserver that is highly optimized for handling many Websocket connections at a low memory footprint.
All apps use that webserver by registering for specific HTTP subpath. So they can all use the same HTTP/HTTPS ports - typically the standard ports.

=== Import Custom SSL Certificate ===
You have to upload a PEM Certificate with the following chain structure and without password encoding.

-----BEGIN CERTIFICATE-----
(certificate: eg. your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: eg. DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: eg. TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: eg. your_domain_name.key)
-----END RSA PRIVATE KEY-----

If you have problems generating the complete and correct certificate chain, you can use tools such as https://whatsmychaincert.com/ as an aid.
'''Please keep in mind that you never give away the private part of your key.'''

=== Known issues ===
*The app platform webserver can use only the default http/https ports 80/443.
*By design, there is no possibility to restore the default webserver certificate on the App Platform, if another certificate was once uploaded. 
**If nevertheless needed, you must login with Putty (see [[#How to retrieve files from the AP| Retrieve files]]) and execute these commands as root:
**''psql -d manager -c "DELETE FROM config WHERE name='webserverCertificate'"''
**''/etc/init.d/S92manager restart''
*The app platform webserver interprets URLs case-sensitive. In other words, <nowiki>http://<addr>/file.txt</nowiki> is not the same as <nowiki>http://<addr>/FILE.TXT</nowiki>

== Database ==
The app platform creates a database for each app instance with a given password. In the installer there will be used randomly generated passwords. You can set a new database password for every instance in the Application Platform.

The apps should store all data in that database. That makes sure that a consistent backup and restore of app instances can be done by the app platform manager.
In hosted scenarios, having separate databases for each instance also makes sure that the data of different customers are clearly separated and can easily be moved from one physical platform to another.

The default configuration decline database request from extern. If you need external access you can change the PGSQL configuration (as root) in the file ''/mnt/sda2/pgsql/pg_hba.conf''.
After editing pg_hba.conf, the database-service has to be restarted with the command <code>/etc/init.d/S50postgresql restart</code>
(Please think about it before you do it, because a better way is to create your own local app with local database access.)

You can find the official documentation for the pg_hba.conf here: https://www.postgresql.org/docs/14/auth-pg-hba-conf.html

Please note that you do this on your own responsibility, that it makes sense to create a backup of the original pg_hba.conf
and that you may break your database server if you do not know exactly what you do!

Sometimes the Apps are not proper working after this. You can wait a while until everything is working again or you go the hard way:
* stop the manager
** <code>/etc/init.d/S92manager stop</code>
* restart the database-service (maybe not really necessary, but makes a good feeling)
**<code>/etc/init.d/S50postgresql restart</code>
* start the manager
** <code>/etc/init.d/S92manager start</code>

=== Nightly database analyse ===

Every database is analysed at night to keep indexes in sync with the data. This triggers a ''vacuumdb -a -z'', which updates optimizer statistics, but does '''not''' shrink the physical size of the database. 
This must be done manually in the instance settings.

== App Platform Manager ==
The App Platform Manager is the central component of the App Platform. It does the following:
* Installing app services by downloading the binaries from an app store.
* Running and monitoring app services. If an app service crashes it is restarted, automatically.
* Management of app instances and providing them with the environment they need:
** A database
** A webserver path
** A password for authentication
* Backup and restore of app instances.
* Collecting debug information like tracing and crash dumps.
* System monitoring (CPU usage, memory usage, etc).

== App Services ==
App services are runned by the App Platform Manager. They implement an interface that is used by the manager to start, stop and configure app instances. Each service runs in a separate child process of the manager.

== App Instances ==
The actual functionality of an app service is provided by app instances. They run in the same process as the app service but have a distinct webserver path and their own database. There can be 0..n instances of an app service. Instances can optionally host (web) apps that can be opened in the myApps client.

Each instance of an App service has two passwords. The instance password itself and a database password. If you want to change it you must update the password on both sides. 
The instance password must match to the password in the corresponding PBX App objects, while one instance can have different App objects. 
The database password must be just known to the manager and not outside of the App Platform.

The ''Database name'' and ''Database user'' are both limited to a length of 63 characters. By default, the App Manager would create ''<domain>''_''<instance-name>'' as value for both. This is why it is recommended to use instance names so that length(name) + length(domain) is less than 63 characters. However, if this is not possible, you can manually shorten the suggested values (both must still be unique on your App Platform).

=== Cleanup database ===
You can cleanup the instance database inside the instance settings. This starts the vacuumdb process for the instance database which frees disk space of deleted rows.
Note that this process locks the database and that sufficient disk space is needed to complete it!

=== External database host ===
You can optionally configure an external database host, if the database shall be hosted on an external host. 
Note that the App Platform Manager still creates a local database, which is then not used as long as the external host is configured.

What are external databases useful for?:
* User data is too large (files are stored as BLOB in the database)
* Other (non-innovaphone) database servers are to be used due to other regulations
* There is already an external database cluster with its own backup/restore processes which should be used
* More performance is required (please note that a local UNIX socket provides much faster results than a remote database server). Depending on the app and the task of the app, it can still be useful to use a separate server if it is faster.

==== Supported database types ====
In principle, ''PostgreSQL'' and ''MySQL'' are supported. However, please note that the respective app must be designed for the target database server type. If an app has been developed for PostgreSQL, it cannot be operated on a MySQL server.

'''Please note:''' All innovaphone apps are developed exclusively as PostgreSQL apps.

MySQL therefore only makes sense if own apps are developed and MySQL or certain MySQL features are to be used. For such apps, it is very important to deactivate the automatic Application Platform APP-Backup.
The database backup process of the App Platform uses PostgreSQL backup commands, which is why the backup would fail, so the app must be excluded from the backup, and you must take care of the backup yourself.

==== Database creation ====
If you use an external database, you have to create the database itself.
The App Platform Manager itself creates a PostgreSQL database like this (you may respect this on your database host to be compatible with the database implementation inside the Apps):
* CREATE DATABASE "dbname" ENCODING 'UTF8';
* CREATE USER "dbuser";
* ALTER USER "dbuser" WITH PASSWORD 'dbpassword';
* GRANT ALL PRIVILEGES ON DATABASE "dbname" TO "dbuser";
* ALTER DATABASE "dbname" OWNER TO "dbuser";
* REVOKE CONNECT ON DATABASE "dbname" FROM public;

==== Database connection ====
There are different possibilities to specify the host. You can use a DNS-Name, IPv4 or IPv6. A port can be optionally added with a colon.

Our PostgreSQL implementation sets sslmode=prefer, so SSL is used by default if enabled on the server.

==== Backup/Restore ====
External databases are still backuped as normal, but you can't restore such a database with the App Platform Manager on the external host! You must restore such a dump manually on your database host.

==== Database redundancy ====
In principle, it is possible to create redundancies for failure scenarios through this function.

However, there are different scenarios that need to be evaluated on a case-by-case basis:

* One database, multiple App Platforms (primary online / secondary '''offline''') where multiple apps access the same database.
** This mode of operation is legal as long as you can really ensure that only one App Platform is active at a time.

* One database, multiple App Platforms (primary online / secondary '''online''') with multiple apps accessing the same database.
** This operating mode cannot be used for innovaphone apps, as the app itself would have to be developed for such a mode, which it is not.

However, we advise great caution here! The use of the same databases from different nodes may only be used if you can ensure that the databases or runtime environments of apps cannot get into a ''split-brain'' mode.

== Relationship between app instances and app objects in the PBX ==
Typically an app instance is connected to one or more app objects in a customer PBX. This is done by configuring the same parameters on both sides:
* URL
* Password
The password is used by the PBX for authenticating itself, users and services against the app instance.

Some apps need a websocket connection with the PBX. When "websocket" is activated at the app object, the PBX establishes a websocket connection to the app instance and provides the APIs that are configured at the app object.

=== Supported scenarios ===
It is important to understand that the concept does not do any assumptions on how PBXes and APs are correlated. So you can have
* One App Platform for one customer
* One App Platform for many customers
* Many App Platforms for one customer
* Many App Platforms for many customers

Attention: The V13 installer can only configure the scenario "''One App Platform for one customer''". If you want to have a different scenario, you have to configure it manually.

For hosting or cloud scenarios you need special scenarios. Please refer our [[Howto:V13 Hosting| V13 Hosting]] instructions.

=== Restrictions ===
Currently we don't have redundancy for app instances or App Platforms.

== Update of the App Platform itself ==
The App Platform is build on top of buildroot and will receive updates and fixes from time to time. 
You can update the used build inside the Manager App by using the '''Update''' button at the top. 

It is strongly advised to make a full backup (VM) or at least backup all apps (Gateway) before you run such an update!

After the update has been downloaded and verified, your App Platform will reboot.
You can check the installation process after the reboot with the following URL: https://IP-of-AP/manager/ramdisk.log

== App services and multi-threading ==
Each App Service runs in a single process with no multi-threading, independent of the instances of the App Service. However, each instance maintains its own database connection and the database responds to this connect with the creation of a new process. Each app service therefore uses 1+''n'' threads (where ''n'' is the number of instances). All communication between app service instances and their clients must pass the single-threaded web server. On platforms with multi-threading support (i.e. VMware or Hyper-V), up to 1 + ''m'' + ''m'' * ''n'' (with ''m'' being the number of Apps and ''n'' the number of instances per App) threads can be utilized.

= AP Manager settings =

== General ==
* ''Enable Developer mode'': in developer mode, apps can be manually uploaded without an App Store
* ''Disable App security'': each App has an own unix user and if this flag is set, the user can login with SSH for debugging
* ''App Store URL'': the URL to the App Store where Apps are searched and also an update of the AP image itself
* ''Devices app URL'': the URL to the Devices App to manage the AP through Devices
* ''Devices app URL 2'': don't use!
* ''App Platform DNS name'': currently not used
* ''NTP server 1/2'': NTP servers for this AP (in addition to NTP servers retrieved by DHCP)
* ''Timezone string'': A timezone string which is used by the App Platform Manager to do certain jobs according to the configured timezone.
** Note that this doesn't change the timezone of the linux itself!
* ''DNS server 1/2'': DNS servers for this AP (in addition to DNS servers retrieved by DHCP)
* ''Database optimization time'': The database optimization process will be started at this hour (local time), with a random offset of up to 7 hours
* ''Command file'': see [[#Backup_of_the_Apps| Backup of Apps]]

== Security ==
* ''Current Webserver certificates'': shows the current certificates with the ability to download them.
* ''Webserver certificate'': upload a webserver certificate in PEM format
* ''AP Manager password'': the password to the web interface of the AP Manager (normally set through Devices)
* ''Linux root user'': password of the root user (normally set through Devices)
* ''Linux admin user'': password of the admin user (normally set through Devices)

== Let's Encrypt ==

Configure the certificate creation by Let's Encrypt here.

* ''Enable'': turns the automatic creation on or off
* ''Let's Encrypt App URL'': the URL of your Connector for Let's Encrypt App Service. You can copy&paste this URL from your Connector for Let's Encrypt PBX Manager Plugin
* ''Let's Encrypt App Password'': the client password of your Connector for Let's Encrypt App Service. You can copy&paste this password from your Connector for Let's Encrypt PBX Manager Plugin
* ''Key length'': 2048, 3072 or 4096 (keep in mind, that [[{{NAMESPACE}}:Certificate_management#Certificate_Key_Length_and_CPU_Usage|a higher value provides higher security but also lower performance!]])
* ''DNS Name'': the external DNS names of your device (up to 100 possible)

== Alarms and events ==
* ''URL'': URL to the Events app
* ''Username/Password'': HTTP credentials of the Events app
* ''Email address'': an email address which will get emails on full disk alarms/warnings
* ''Threshold'': All Apps will be stopped and an hourly email sent on reaching this threshold. An alarm is generated 10% before reaching this threshold and an email is sent every 24 hours.

== SMTP ==
SMTP server settings for sending emails from within the AP Manager.

Starting with 16r1 you also can configure OAuth2 Authentications. You can have a look into our HowTo Article for assistance: [[Howto16r1:Configure OAuth2 E-Mail]]

== Replication ==
App Platform [[#App Platform replication|replication settings]]

== Registered Access Domains ==

== Update ==
Updates the App Platform to the latest image available on the App Store.

== Restart ==
Restarts the App Platform.

== Shutdown ==
Shuts down the App Platform.

= App Platform replication =

== Requirements ==

* 13r3 or above on both standby servers and the primary server
* at least an App Platform image starting with version 110002 (otherwise postgresql is too old)
* standby and primary servers must have the same system architecture
** arm gateways (IPx11) just with arm gateways (IPx11)
** arm64 gateways (IPx13) just with arm64 gateways (IPx13)
** x86_64 virtual machines just with x86_64 virtual machines
* the disk size on standby servers must be at least equal as the disk size on the primary server

== General ==
The configuration is done within the App Platform Manager next to the settings button under "Replication".

=== Off ===
No replication is done at all.

=== Primary ===
The App Platform acts as primary server for one or multiple standby servers. 
Max 8 standby servers can be configured. 
 
Every standby server must get a unique name on the primary server which is then also configured on the standby server itself. This is due to the fact, that the primary server preserves data for every standby server while it's not reachable. 
A standby server name must be a valid domain name, although this name is currently not used as DNS name (but might be used in the future). 
 
The password is randomly pregenerated and must be used as handed by the App Platform Manager.

==== PostgreSQL port ====
The default PostgreSQL port is 5432 and can't be changed on the primary. It must be reachable through your firewall or at least forwarded on a different port towards this App Platform on port 5432.

=== Standby ===
Configure the password from the primary and one of the not yet used standby server names. 
The host and port must be reachable through the network. You can specify a non default port which then must be forwarded somewhere else to port 5432 on your primary.

*Note: Do '''not''' configure the same standby name on different standby servers, as this will break the replication on at least one standby! 
*Note: On a standby, all '''locally installed apps are removed''' during installation

== Failure detection ==

The replication state on both primary and standby servers are continuously monitored. 
In case of a broken connection, an alarm is triggered at once and just cleared if the failure goes away. 
 
If such an alarm lasts for 5 minutes an email is send. The recipient address must be configured in the App Platform Manager settings under "Alarms and Events" and you must also provide a valid SMTP configuration.

== Failover ==

There is no automatic failover procedure. If you detect the failure state, you must get active yourself.

=== Standby down ===

Fix the standby server and see if the replication comes up again. If not, setup a new standby server which will replicate the whole database cluster from scratch.

=== Primary down ===

If the primary is down and cannot be brought into life again, you must take the following steps, depending on your configuration:

==== One standby server ====

* Disable the replication in the replication configuration. You will then have a standalone App Platform afterwards.

==== Multiple standby servers ====

* Change the replication type on one of the standby servers from standby to primary. Please note that the other standby entries must still exist here (they are automatically offered)!
* Change the host entry on the other standby servers to the new standby server. The standby server will sync the whole database cluster again, which will take time.

==== Configuration changes ====

You must also tell the PBXes and other tools to use the new primary server.

* You may simply change the IP address behind the DNS of your primary server to point to the new primary server.
**Note: to ensure rapid recognition of the new DNS target, the definition of an appropriate TTL value is recommended
* Without DNS, you must currently modify the configuration by replacing the IP address of the old primary with the new address.
** This must be done in every master PBX configuration.
** This must be done in every App configuration which may use this IP address, e.g. Devices which rolls out an alarm server configuration

== App Platfom update ==

If you're running an active standby server and the major version of the PostgreSQL database didn't change, you can simply update primary and standby servers independently. 
 
If it contains a ''new major version'' of the PostgreSQL database, you must follow these steps:

* deactivate replication on all standby servers (which promotes these standby servers to active servers)
* ensure that the '''same''' App Platform Manager version is running on primary and standby servers!
* perform the App Platform update on the primary server
* perform the App Platform update on the standby servers
* reactivate replication on the standby servers (which will do a full replication again, so it might take some time)

Alternativly you may setup the standby server from scratch directly with the new App Platform image version.

Sadly there is currently no better method offered by PostgreSQL to perform such an upgrade.

See also https://wiki.innovaphone.com/index.php?title=Howto14r2:Firmware_Upgrade_V14r1_V14r2#App_Platform_and_Apps

== Technical backgrounds ==

=== Streaming replication ===

We use the asynchronous [https://www.postgresql.org/docs/9.3/warm-standby.html#STREAMING-REPLICATION streaming replication of PostgreSQL]. A transaction thus just waits for a commit on the primary server. Standby servers will receive the transaction asynchronously afterwards to avoid a reduced writing performance. 
A primary server keeps the neccessary WAL files for every standby server until the standby fetched the neccessary information. 
This fact can lead to higher disk space usage on the primary if one or multiple standby servers are offline for a while.

Take care to fix broken replications as soon as possible to avoid a full disk on the primary server!

=== What is replicated ===
The whole database cluster of an app platform is replicated. This includes every database of every instance and the database of the App Platform Manager itself. 

=== App Services on standbys ===
The database of the App Platform Manager itself also contains the App service binaries to be able to restore applications in a failover case. 
You do not have to install App services on the standby if you install them on the primary. 
App Platform Manager and Webserver can be updated as usual through the App Store or the Devices App if the standby is connected to Devices.

=== App Platform Manager configuration of the standby server ===
The App Platform Manager configuration of the standby server cannot be stored inside the database, as the database is readonly. So it is stored inside a configuration JSON file under ''/home/root/standby.conf''. 
This configuration is backed up as usual by a Devices backup job and can be also manually restored on a standby (not on a primary though!).

Configuration options from the primary are not synced to the standby server, as the standby server has its own configuration (as it could be in a different network etc.)!

=== No automatic failover ===

There is currently no automatic failover mechanism. PostgreSQL doesn't offer multi master replication, so writing is just possible on the primary itself. Standby servers have a readonly database. 
Let's consider the following use case if we would implement an automatic failover with the current technical possibilities: 
* The primary server is connected to a master PBX.
* A slave PBX is also connected to the primary server in another location.
* A standby server is in this location and replicates from the primary.
* The internet connection between primary and standby fails.
* The standby promotes itself to primary, so that the master PBX now writes to the old primary and the slave PBX now writes to the "new" primary.
* The internet connection comes up again and both primary and standby servers now have databases which are out of sync and which cannot be merged.

=== Security ===

* port 5432 must be reachable on the App Platform
* For every standby a PostgreSQL user is created with the REPLICATION role on the primary. Just this user has access to the database server from non localhost connections.
* You cannot establish a standard connection with such a user and modify/read from tables.
* The replication connection is established over TLS by default.

= App Installer PBX Manager Plugin =
== Requirements ==

* V14 and above

== General ==

The app installer plugin allows IT administrator (with access to the PBX Manager) to install/update/delete new apps from the innovaphone app store including Partners apps. It is automatically available with existing app platforms or after adding a new one in the PBX Manager.
It offers a view to the App Platform Manager‘s App Store with all the available functionalities and simplifies the install, update and uninstall of apps.

== Dedicated AP for each user ==

Installing a new app will install the app service and add a new instance with the user’s domain. The instance is automatically started. 
This further enables the configuration of the instance through its respective PBX Manager plugin. 
Uninstalling the app will remove the app service and the corresponding instance.

== Shared AP between users ==

Installing a new app works in a similar way to that of the dedicated AP. However, each time a new user installs the app, only a new instance is created if the app service is already installed. 
A user can uninstall the app, in this case the corresponding instance is deleted. If no more instances exist, then the app service is uninstalled. 
The administrator can only update the app service in such scenario.

= Known Issues =

== Reboot after an image update hangs (ARM/ARM64 gateway) ==

If it happens, that the App Platform doesn't recover after the reboot, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
If '''Kernel command line''' is set to '''/dev/ram0''', the App Platform booted the ramdisk. 
 
Try to fetch the upgrade log file:
https://[APP-PLATFROM-IP/DNS]/manager/ramdisk.log
 
If this doesn't work, try to login with putty in this case (default credentials admin/ipapps and root/iplinux) and issue this command: 
''cat /apps/install_step1.log'' 
 
If this file contains '''finished''' at the end, you can reconfigure the settings under App Platform -> General: 
* press '''Stop'''
* Initrd file: empty
* Kernel command line:
** IPxx11: '''root=/dev/sda3'''
** IPxx13: '''root=/dev/nvme0n1p3'''
* Ramdisk size: empty
* press '''Start'''

The App Platform should boot and run the already updated image.

<pre style="color: red; font-size:150%;">---WARNING---
If the file doesn't contain "finished" at the end, you may still need to wait, as an upgrade may take some time!
Do not reconfigure without being sure that the upgrade has finished, otherwise your system may won't run!</pre>

== Reboot after an image update boots always into rescue mode (virtual machine) ==

This most likely means that the image installation didn't finish the first time and was interrupted before the bootloader settings could be changed back to the default partition. 
 
If your App Platform doesn't boot or isn't normally accessible after manual selection of the standard entry in the boot menu, you need to '''revert''' to a '''snapshot/backup''' prior to the update. 
If your App Platform runs normally though, you can follow this instruction to change the default boot entry: 
 
* boot into the '''rescue''' partition
* login with root/iplinux
* edit the file /boot/grub/grub.cfg
** search the line with '''set default=0''' and change it to '''set default=1'''
** reboot

== App Platform doesn't start after an update ==

=== Gateway ===
If it happens, that the App Platform doesn't want to start an update, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
* '''Shutdown''' the App Platform and '''Stop''' it 
* Set '''Kernel command line''' to '''/dev/ram0''' 
* Set '''Initrd file''' to '''ramdisk.ext2.xz''' 
* Set '''Ramdisk size''' to '''100000''' 
* '''Start''' the App Platform now. 

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

Note: This process can take a while, after it's finished it reboots and automatically change the '''Kernel command line''' value.

=== Virtual Machine ===

Boot into the '''rescue''' partition.

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

=== It still doesn't start ===

If it still doesn't start, configure the App Platform to boot from /dev/sda3|IPx11 or /dev/nvme0n1p3|IPx13 (or inside a VM start the second boot loader entry) and login with SSH as root.
Then do a first check to verify that you have a specific error due to an incomplete update or a [[Howto15r1:Firmware Upgrade V14r2 V15r1#AP Upgrade to Image 130006|wrong update order]]:

* /etc/init.d/S92manager stop
* /apps/manager/manager
* if this outputs '''error while loading shared libraries: libcrypto.so.3:''' you have a manager version which cannot run on the current image.

In this case you must download an older build (14r1 1410593):

* /etc/init.d/S92manager stop
* wget --no-check-certificate -O /apps/manager/manager https://webbuild.innovaphone.com/1410593/arm/manager/manager
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* wget --no-check-certificate -O /apps/webserver/webserver https://webbuild.innovaphone.com/1410593/arm/webserver/webserver
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* chown root:root /apps/manager/manager
* chown root:root /apps/webserver/webserver
* chmod +x /apps/manager/manager
* chmod +x /apps/webserver/webserver
* echo 110000 > /mnt/sda1/label
** this allows the manager to perform an image update again
* /etc/init.d/S92manager start
* now perform an image update and '''afterwards''' update your apps again

== Webserver doesn't respond after an image update ==

If you can't reach the web UI after an image update, please try to connect with SSH as admin user and delete old coredumps, which may prevent the App Platform Manager from starting correctly:
* su root (become root)
* rm -f /mnt/sda2/log/core_dumps/*/*
* /etc/init.d/S92manager restart

Check if you can now reach the App Platform again.

= Tracing =
Each App Service has its own log file, which can be accessed through the Manager App. You can configure a log file size for each App Service. 
Each App Intance has its own trace flags. The following trace flags can be set: 

* Alarm client: used by the manager to send alarms to an alarm server
* App: logs from the App Service itself
* App WebSocket: logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
* AppSharing: just native clients
* AppProxy: just native clients, logs requests which are proxied between the local webserver and the remote server
* Audio: just native clients
* Browser: just native clients
* Command: the command interface is used to execute shell commands, e.g. used by the manager App
* Config: logs config changes of an App
* Database: database logs
* DB files: database file logs
* DNS: DNS request logging
* DTLS: just native clients, DTLS request logging
* Ethernet: interface to get ethernet adapater infos, just manager App
* File: logs for file system access (synchronous), e.g. manager App
* Files: logs for file system access (asynchronous)
* HTTP client: http client logs
* HTTP file: logs for static HTTP files
* ICE: just native clients
* LDS: local domain sockets
* Media: just native clients
* Media channel: just native clients
* Process: IProcess interface logs which is used for spawning, killing processes etc.
* SMTP: SMTP client logs
* TCP: TCP logs
* Time: ITime interface logs
* TLS: TLS logs
* TURN: just native clients
* UDP: UDP logs
* Video: just native clients
* WebSocket client: logs outgoing websocket connections
* Webserver traffic: logs incoming HTTP traffic, which is forwarded from the webserver to the App
* WebDAV service: logs WebDAV requests to the App
* Webserver: enables webserver specific logs

== RPCAP ==

If you open the Manager App, click on the Manager in the left list and then on the Diagnostics button, you can enable RPCAP. 
You can add the interface in wireshark with the string:
rpcap://<APP-Platform-IP>/eth0

'''Please don't forget to disable RPCAP after your testing!'''

= How-Tos =

== How to retrieve files from the App Platform ==
To retrieve files from the App Platform which can not be retrieved via the App Platform manager UI, you can connect to the App Platform using the SCP protocol on port 22. 
 
First copy files to /home/admin as root with Putty or another SSH client:
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''su root'' to be root (''iplinux'' as default password)
 
You can now copy files to ''/home/admin'' (e.g. from /var/log/apps/manager/...). 
 
You can create a tar archive with all logs like this:
* cd /home/admin
* tar -cf - /var/log/* | xz -z - > log.tar.xz
** you may want to exclude coredumps (due to their size):
** tar -cf - --exclude=/var/log/core_dumps/* /var/log/* | xz -z - > log.tar.xz
* chown admin:admin /home/admin/log.tar.xz
 
Then copy the files to your local system, e.g. with WinSCP 
* use ''SCP'' as protocol (NB: WebDAV is not supported on most of the directories on the App Platform )
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''/home/admin'' as start directory
* copy the needed files

== App Platform disk space warning ==

If the configured threshold is reached, all Apps are stopped inside the App Platform . You must then free disk space somehow.

=== Find large instances ===
Click through your apps in the tree on the left side and take a look at the database size of each instance.

=== Delete data inside an instance ===
It depends on the type of app if you can delete data or not. E.g. you can start the Files app and delete files inside this app. 
This won't reclaim disk space though due to the way how PostgreSQL databases work, so you need to follow this guide to reclaim the disk space:

* start the corresponding App
* delete data inside the App
* optimize disk usage of the database by cliking on the button "Clean up database" under Edit instance. If this does not help, continue with the following steps.
* stop the corresponding App again
* download a backup of the instance (backup button at the top), this backup contains the whole instance data, also the password of the instance
* delete this specific instance
* restore the downloaded backup (restore button at the top)

Depending on the hardware and the size of the instance, this process may take hours to complete!

=== Resize the disk ===
The resizing of a disk is just possible for virtual machines, see [[#Resizing the disk of a Virtual machine|Resizing the disk of a Virtual machine]].

=== Delete the whole instance ===
If there is no other possibility, you can delete the whole instance. Afterwards you recreate the instance with the same values and a new random password. Don't forget to set this password in the corresponding PBX App objects though!

=== Restart the Apps or the App Platform ===
If you have enough disk space again, you must either restart the whole App Platform or you manually start all Apps again.

== App Platform/Apps app not online anymore due to full disk ==
If the apps app is not online anymore and you can't access any apps anymore, try to login with an SSH client to see if your disk is full.
Login as admin and afterwards as root (su root). 
 
* issue '''df -h''' and see the disk usage of /dev/sda2, if this is 100%, your disk is too full
* stop the manager
** /etc/init.d/S92manager stop
* empty the 500 MB file, which is exactly for this case here (manager must be 13r1 SR9 or higher to have this file)
** echo "" > /mnt/sda2/empty_if_no_space
* delete log files to recover some space
** rm /var/log/apps/*/*
** rm /var/log/core_dumps/*/*
* restart the postgresql server (see the output if this worked or not)
** /etc/init.d/S50postgresql restart
* restart the manager
** /etc/init.d/S92manager restart
* wait until everything is online again
* open the Apps app and try to find the instance which uses the most disk space and try to delete files/content from it
** you may want to stop all app services first to prevent more writes to the database
** if not possible, you can delete this instance, but you'll loose all data from this instance then!
* after that you can try [[{{NAMESPACE}}:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files|Reference14r2:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files]] to free up space
** If this does not work you can create a backup from the database, delete the database and import the database again.
* free up at least 500 MB so that the manager can create the file again
* delete /mnt/sda2/empty_if_no_space if you are done and restart the manager:
** rm /mnt/sda2/empty_if_no_space
** /etc/init.d/S92manager restart
** the manager restart automatically recreates the empty_if_no_space file if this file doesn't exist

Make sure, that you do '''not''' have backups configured to a local files instance while this files instance is not excluded from backups.
An instance can be excluded from backups in the instance settings in the App Platform Manager.

If all of this doesn't help, you can resize the file system on a VM:
* proceed with [[{{NAMESPACE}}:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine|Reference14r2:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine]]

== Resizing the disk of a Virtual machine ==

Do '''NOT''' resize if you're running an App Platform version higher than '''110000''' and lower than '''110027''' or '''130007''' and lower than '''130015''' or your data will be lost!
Please update your App Platform to version 130015 or higher before you start resizing your disk.

* stop the VM
* expand the disk using your VM utilities
* start the VM and boot from the first boot entry '''rescue/setup'''
* login with '''root''' and '''iplinux'''
* execute this command: '''/home/root/install_step1.sh log.txt resize'''
* the VM reboots automatically after a successful resize

== Shrink the physically size of PostgreSQL database files ==
Tuples that are deleted in your database are not physically removed from the database-file. So the claimed space on the harddisk is still in use after the delete operation.
If you need to free up some disk space you can force to reorganize the physically database-file on your harddisk.

You can also start this process through the instance settings as long as the App Platform Manager is still running.

'''Important: You are operating on the Database, you have to make a Backup of your Database before you do this!'''

Login via SSH to the APPlatform with the ''admin'' User
su root

=== All databases ===
/etc/init.d/S92manager stop # not always needed, but in case of database errors recommended, of course no app is online then
sudo -u postgres reindexdb -a
sudo -u postgres vacuumdb -a -f
/etc/init.d/S92manager restart # just execute if the manager has been stopped above

=== single database ===
sudo -u postgres reindexdb -d dbname # for a single database with dbname
sudo -u postgres vacuumdb -d dbname -f # for a single database with dbname

Note: This may take some time and the App database is not available during this time

After the process you can check the free dispace via <code>df -h</code>. You can check the claimed space from the database file with the command <code>du -sh /mnt/sda2/pgsql/</code>.

== Change IP Addresses / DNS Names / System Name ==

If you want to change the System Name or the DNS Name of the PBX and/or App Platform Platform you must change records manually '''in the described order'''!
You have to know the Admin password to directly Login to the App Platform .

=== App Platform ===
; Settings - General
* ''Devices app URL''
* ''App platform DNS name''

; Settings - Alarms and Events
* ''URL''

; All Instances
* ''Domain''
* ''Webserver path''

=== PBX ===
Download the configuration and ''search/replace'' in the config file. Upload the config file and reboot.

Manual:
* ''URL'' in all PBX Object (Apps, Voicemail ...)
* [[{{NAMESPACE}}:Gateway/CDR|CDRx]]
* [[{{NAMESPACE}}:PBX/Config/General|IP address for App Platform]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reset Password Page]]
* [[{{NAMESPACE}}:PBX/Config/Authentication|Verification link]]

Depending on your change you have to activate/deactivate the Setting [[{{NAMESPACE}}:PBX/Config/General|Operation without DNS]]

=== Additional Devices / Steps ===
* ''Devices Registration URL''
** There is no automatism to change the URL on all devices in your setup.
** If you have the option to use DHCP, you can temporarily overwrite the [[{{NAMESPACE}}:Services/Update|Update URL]] and execute a [[{{NAMESPACE}}:Concept_Update_Server|custom update script]] to change the ''Device Registration URL''
* ''Alarm server''
* Reverse Proxy configuration
* Change ''Domain Name'' in Devices if you have also changed the system name

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

initial error at 1500329378: ext4_journal_start_sb:328
last error at 1500329378: ext4_journal_start_sb:328

Or you get events like "Broken file system" from your App Platform .

This indicates a file system failure on the Linux Installation.

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

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

=== Gateway ===

* Open the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the Kernel command line from root=/dev/sda3 (or /dev/nvme0n1p3) to root=/dev/ram0
** modify the Initrd file to ramdisk.ext2.xz
** modify the ramdisk size to 100000
** start Linux again
:: This will run Linux on another (hopefully sane) partition.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code> on IPx10/IPx11 gateways
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code> on IPx10/IPx11 gateways
** on the command prompt, use <code>e2fsck -p -f /dev/nvme0n1p2</code> on IPx13 gateways
** on the command prompt, use <code>e2fsck -p -f /dev/nvme0n1p3</code> on IPx13 gateways
:: this should fix any issue on the file system

* go back to the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/ram0'' to <code>root=/dev/sda3</code> (IPx10/IPx11) or to <code>root=/dev/nvme0n1p3</code> (IPx13)
** clear the Initrd file field
** clear the ramdisk size field
** start Linux again
:: This will run Linux on the original partition.

=== VM ===

Restart the VM and select the first entry in the boot menu from grub.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system
* Reboot your VM
[[Category:Concept]]

== How to create a memory dump of a running process ==

Sometimes it's usefull to have a memory dump of a running process to investigate certain issues.

* login with SSH and become root
* find out the PID of the relevant process, e.g. with ''ps aux | grep /apps/manager/manager | grep -v grep''
* gdb --pid PID -ex gcore --batch
* this creates a core file core.PID
* download this core file with WinSCP or similar tools

== Move instance database to external database host ==

In case you want to use an external database server instead of the integrated:

* download a backup of the specific instance over the App Platform Manager
* create a postgresql database on the external host:
** createdb --encoding=UTF-8 exampledb
* restore the backup
** pg_restore -d exampledb backup-exampledb.dump
* change the ownership to a specific postgresql user (which you have to create yourself first)
** psql -d postgres -c "ALTER DATABASE exampledb OWNER TO exampleuser"
* configure the database host, name, user and password on the instance inside the App Platform Manager

Reference14r2:Concept App Platform

2026-05-08T08:02:52Z

Dde: /* Reboot after an image update hangs (ARM gateway) */

= General =
* V13 uses [https://buildroot.org/ buildroot]
* this is an own (innovaphone) collection of packages
* For further information see: [https://buildroot.org/docs.html Buildroot Documentations]

== Requirements ==

* V13 or above
* Gateway (arm): IPx10 (with CF card) or IPx11 (with mSATA SSD)
* Gateway (arm64): IPx13 (with m2 SSD)
* Virtual (x86_64)
** HyperV with [https://docs.microsoft.com/de-de/windows-server/virtualization/hyper-v/deploy/upgrade-virtual-machine-version-in-hyper-v-on-windows-or-windows-server#supported-virtual-machine-configuration-versions VM-configuration Version] 6.2 (minimum: Windows 10 or Windows Server 2016)
** VMWare
** Proxmox/KVM/Qemu

== Default credentials ==

'''During INSTALL, the default passwords are replaced with the global Admin PW!'''
* SSH-Login with '''admin''' and '''ipapps'''
* root login with '''root''' and '''iplinux''' (the root login is not directly possible, you have to login as admin first and use the command ''su root'')
* manager App (web login) '''pwd'''

= App Platform - arm/arm64 (Gateway)=

* The installation image has a size of ~50MB. During installation, the following partitions are created<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 fat32: 200MB (contains ramdisk, rootfs and kernel)
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB

When comparing potential performance of the IPxx11 platform compared to the IPxx10 platform, there are some major differences:
* SSDs found in the xx11 are faster and more reliable than the CF found in the xx10
* the available RAM for the App Platform (as specified in column ''RAM for LAP (GB) out of RAM'' in chapter ''Technical data and recommended number of users supported'' of [[Howto:How to implement large PBXs#Technical data and recommended number of users supported|How to implement large PBXs]]) is factor 6 larger on the xx11 (1,536 GB) than on the xx10 (0,256 GB))
* the xx11 has gigabit Ethernet while the xx10 has 100Mbps Ethernet. The xx10 is therefore not well suited for Apps with larger network traffic, such as Recordings
* the CPU of the xx11 (although it runs on the same frequency) is roughly 20% faster than the xx10

While it is hard to predict the performance of the App Platform in a specific scenario, we see that in a real life environment an App Platform running on an xx11 platform can well support 150 users. The xx10 platform is estimated to support 120 users. Because CPU performance is the limiting factor, larger setups can be built based on the virtual machine platform (see [[#App services and multi-threading|App services and multi-threading]] below).

<references/>

= App Platform - x86-64 (Virtual Machine 64bit) =

* The default disk size is 16GB. It should be increased '''before''' the first start if needed!
* Multiple CPUs are supported, default is one CPU
* default RAM: 512MB
* static IP address, DNS, Gateway can be configured with the command '''setip''' on the console. Run '''setip --help''' to get a list of parameters. (Example: setip --addr=x.x.x.x --mask=x.x.x.x --gateway=x.x.x.x --dns1=x.x.x.x)
* If you have permission problems change to su user (Password is iplinux or your new admin password)
* To figure out your ip address you can use the command: ''ip address'' on the console.
* '''loadkeys de''' can be used to change to german keyboard layout (etc.)
* partitions<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 ext2: 350MB (contains ramdisk, rootfs and kernel)
*** the real partition format size is smaller but there is no need to monitor sda1 as sda1 won't grow during usage of the App Platform
*** sda1 is completely exchanged during an image update and its size might have changed but will never exceed these 350MB
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB
* VMWare Tools: Open VM Tools
* Qemu Guest Agent: installed since 110032
** The qemu guest agent can be configured in Proxmox with ''Virtio'' or ''ISA''. Before version 130012, you must use ISA, as Virtio was not supported with older versions.

<references/>

= Installation =
==ARM Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-armel.img'' image file.
* The installation runs without any further required step.

==ARM64 Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-arm64.img'' image file.
* The installation runs without any further required step.

==Virtual machine==

* Import the image into your server environment.
** Proxmox: follow this description here, just with the app-platform-ova.zip: https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Proxmox_VE
* Edit the disk size, if needed.
* Start the machine and wait until it reboots and starts again.
* Note: If you need to access an IP addresses available through a VPN connection from from inside the virtual machine, it could be that you need to set the network of your VM to NAT (and also add the URL for an IP to /etc/hosts)

[https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Configuration More Configuration Hints regarding VM Ware]

== Backup of the Apps ==

Each App Service can have multiple instances and each instance has its own database. The manager app itself also has its own database. 
There are no other files which need to be backuped. 
The standard way to backup the databases is through the Devices App [[{{NAMESPACE}}:Concept_App_Service_Devices#Backups]]. 
 
An alternate way is to use a command file which is similar to the command files from the firmware.

===Commands===
* '''times''' 0,12 # backup only at 0 or 12 o'clock
* '''backup-instances''' http://user:pw@ip/path/#I-#D.dump PUT
** PUT and POST are supported, all instances including the manager itself are saved
* '''backup-instance''' http://user:pw@ip/path/#I-#D.dump apidemo example.com PUT
** backup a single instance with instance name and instance domain
* '''backup-manager''' http://user:pw@ip/path/#I-#D.dump

===Hash parameters===
* #L App Platform label (neu), e.g. 10024
* #A App label (neu), e.g. 130004
* #I instance name (neu), e.g. reporting1
* #D instance domain (neu), e.g. innovaphone.com
* #m MAC address of the LAP, e.g. 00ab11eeff
* #d Current date and time (plain UTC without daylight saving and timezone adjustments) 20051010-170130
* #bn rolling backup index (n >=0 and <= 9, just one digit)
* ## escapes a hash mark

= App Platform Infrastructure and Concept =
== Webserver ==
The app platform includes a webserver that is highly optimized for handling many Websocket connections at a low memory footprint.
All apps use that webserver by registering for specific HTTP subpath. So they can all use the same HTTP/HTTPS ports - typically the standard ports.

=== Import Custom SSL Certificate ===
You have to upload a PEM Certificate with the following chain structure and without password encoding.

-----BEGIN CERTIFICATE-----
(certificate: eg. your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: eg. DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: eg. TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: eg. your_domain_name.key)
-----END RSA PRIVATE KEY-----

If you have problems generating the complete and correct certificate chain, you can use tools such as https://whatsmychaincert.com/ as an aid.
'''Please keep in mind that you never give away the private part of your key.'''

=== Known issues ===
*The app platform webserver can use only the default http/https ports 80/443.
*By design, there is no possibility to restore the default webserver certificate on the App Platform, if another certificate was once uploaded. 
**If nevertheless needed, you must login with Putty (see [[#How to retrieve files from the AP| Retrieve files]]) and execute these commands as root:
**''psql -d manager -c "DELETE FROM config WHERE name='webserverCertificate'"''
**''/etc/init.d/S92manager restart''
*The app platform webserver interprets URLs case-sensitive. In other words, <nowiki>http://<addr>/file.txt</nowiki> is not the same as <nowiki>http://<addr>/FILE.TXT</nowiki>

== Database ==
The app platform creates a database for each app instance with a given password. In the installer there will be used randomly generated passwords. You can set a new database password for every instance in the Application Platform.

The apps should store all data in that database. That makes sure that a consistent backup and restore of app instances can be done by the app platform manager.
In hosted scenarios, having separate databases for each instance also makes sure that the data of different customers are clearly separated and can easily be moved from one physical platform to another.

The default configuration decline database request from extern. If you need external access you can change the PGSQL configuration (as root) in the file ''/mnt/sda2/pgsql/pg_hba.conf''.
After editing pg_hba.conf, the database-service has to be restarted with the command <code>/etc/init.d/S50postgresql restart</code>
(Please think about it before you do it, because a better way is to create your own local app with local database access.)

You can find the official documentation for the pg_hba.conf here: https://www.postgresql.org/docs/14/auth-pg-hba-conf.html

Please note that you do this on your own responsibility, that it makes sense to create a backup of the original pg_hba.conf
and that you may break your database server if you do not know exactly what you do!

Sometimes the Apps are not proper working after this. You can wait a while until everything is working again or you go the hard way:
* stop the manager
** <code>/etc/init.d/S92manager stop</code>
* restart the database-service (maybe not really necessary, but makes a good feeling)
**<code>/etc/init.d/S50postgresql restart</code>
* start the manager
** <code>/etc/init.d/S92manager start</code>

=== Nightly database analyse ===

Every database is analysed at night to keep indexes in sync with the data. This triggers a ''vacuumdb -a -z'', which updates optimizer statistics, but does '''not''' shrink the physical size of the database. 
This must be done manually in the instance settings.

== App Platform Manager ==
The App Platform Manager is the central component of the App Platform. It does the following:
* Installing app services by downloading the binaries from an app store.
* Running and monitoring app services. If an app service crashes it is restarted, automatically.
* Management of app instances and providing them with the environment they need:
** A database
** A webserver path
** A password for authentication
* Backup and restore of app instances.
* Collecting debug information like tracing and crash dumps.
* System monitoring (CPU usage, memory usage, etc).

== App Services ==
App services are runned by the App Platform Manager. They implement an interface that is used by the manager to start, stop and configure app instances. Each service runs in a separate child process of the manager.

== App Instances ==
The actual functionality of an app service is provided by app instances. They run in the same process as the app service but have a distinct webserver path and their own database. There can be 0..n instances of an app service. Instances can optionally host (web) apps that can be opened in the myApps client.

Each instance of an App service has two passwords. The instance password itself and a database password. If you want to change it you must update the password on both sides. 
The instance password must match to the password in the corresponding PBX App objects, while one instance can have different App objects. 
The database password must be just known to the manager and not outside of the App Platform.

The ''Database name'' and ''Database user'' are both limited to a length of 63 characters. By default, the App Manager would create ''<domain>''_''<instance-name>'' as value for both. This is why it is recommended to use instance names so that length(name) + length(domain) is less than 63 characters. However, if this is not possible, you can manually shorten the suggested values (both must still be unique on your App Platform).

=== Cleanup database ===
You can cleanup the instance database inside the instance settings. This starts the vacuumdb process for the instance database which frees disk space of deleted rows.
Note that this process locks the database and that sufficient disk space is needed to complete it!

=== External database host ===
You can optionally configure an external database host, if the database shall be hosted on an external host. 
Note that the App Platform Manager still creates a local database, which is then not used as long as the external host is configured.

What are external databases useful for?:
* User data is too large (files are stored as BLOB in the database)
* Other (non-innovaphone) database servers are to be used due to other regulations
* There is already an external database cluster with its own backup/restore processes which should be used
* More performance is required (please note that a local UNIX socket provides much faster results than a remote database server). Depending on the app and the task of the app, it can still be useful to use a separate server if it is faster.

==== Supported database types ====
In principle, ''PostgreSQL'' and ''MySQL'' are supported. However, please note that the respective app must be designed for the target database server type. If an app has been developed for PostgreSQL, it cannot be operated on a MySQL server.

'''Please note:''' All innovaphone apps are developed exclusively as PostgreSQL apps.

MySQL therefore only makes sense if own apps are developed and MySQL or certain MySQL features are to be used. For such apps, it is very important to deactivate the automatic Application Platform APP-Backup.
The database backup process of the App Platform uses PostgreSQL backup commands, which is why the backup would fail, so the app must be excluded from the backup, and you must take care of the backup yourself.

==== Database creation ====
If you use an external database, you have to create the database itself.
The App Platform Manager itself creates a PostgreSQL database like this (you may respect this on your database host to be compatible with the database implementation inside the Apps):
* CREATE DATABASE "dbname" ENCODING 'UTF8';
* CREATE USER "dbuser";
* ALTER USER "dbuser" WITH PASSWORD 'dbpassword';
* GRANT ALL PRIVILEGES ON DATABASE "dbname" TO "dbuser";
* ALTER DATABASE "dbname" OWNER TO "dbuser";
* REVOKE CONNECT ON DATABASE "dbname" FROM public;

==== Database connection ====
There are different possibilities to specify the host. You can use a DNS-Name, IPv4 or IPv6. A port can be optionally added with a colon.

Our PostgreSQL implementation sets sslmode=prefer, so SSL is used by default if enabled on the server.

==== Backup/Restore ====
External databases are still backuped as normal, but you can't restore such a database with the App Platform Manager on the external host! You must restore such a dump manually on your database host.

==== Database redundancy ====
In principle, it is possible to create redundancies for failure scenarios through this function.

However, there are different scenarios that need to be evaluated on a case-by-case basis:

* One database, multiple App Platforms (primary online / secondary '''offline''') where multiple apps access the same database.
** This mode of operation is legal as long as you can really ensure that only one App Platform is active at a time.

* One database, multiple App Platforms (primary online / secondary '''online''') with multiple apps accessing the same database.
** This operating mode cannot be used for innovaphone apps, as the app itself would have to be developed for such a mode, which it is not.

However, we advise great caution here! The use of the same databases from different nodes may only be used if you can ensure that the databases or runtime environments of apps cannot get into a ''split-brain'' mode.

== Relationship between app instances and app objects in the PBX ==
Typically an app instance is connected to one or more app objects in a customer PBX. This is done by configuring the same parameters on both sides:
* URL
* Password
The password is used by the PBX for authenticating itself, users and services against the app instance.

Some apps need a websocket connection with the PBX. When "websocket" is activated at the app object, the PBX establishes a websocket connection to the app instance and provides the APIs that are configured at the app object.

=== Supported scenarios ===
It is important to understand that the concept does not do any assumptions on how PBXes and APs are correlated. So you can have
* One App Platform for one customer
* One App Platform for many customers
* Many App Platforms for one customer
* Many App Platforms for many customers

Attention: The V13 installer can only configure the scenario "''One App Platform for one customer''". If you want to have a different scenario, you have to configure it manually.

For hosting or cloud scenarios you need special scenarios. Please refer our [[Howto:V13 Hosting| V13 Hosting]] instructions.

=== Restrictions ===
Currently we don't have redundancy for app instances or App Platforms.

== Update of the App Platform itself ==
The App Platform is build on top of buildroot and will receive updates and fixes from time to time. 
You can update the used build inside the Manager App by using the '''Update''' button at the top. 

It is strongly advised to make a full backup (VM) or at least backup all apps (Gateway) before you run such an update!

After the update has been downloaded and verified, your App Platform will reboot.
You can check the installation process after the reboot with the following URL: https://IP-of-AP/manager/ramdisk.log

== App services and multi-threading ==
Each App Service runs in a single process with no multi-threading, independent of the instances of the App Service. However, each instance maintains its own database connection and the database responds to this connect with the creation of a new process. Each app service therefore uses 1+''n'' threads (where ''n'' is the number of instances). All communication between app service instances and their clients must pass the single-threaded web server. On platforms with multi-threading support (i.e. VMware or Hyper-V), up to 1 + ''m'' + ''m'' * ''n'' (with ''m'' being the number of Apps and ''n'' the number of instances per App) threads can be utilized.

= AP Manager settings =

== General ==
* ''Enable Developer mode'': in developer mode, apps can be manually uploaded without an App Store
* ''Disable App security'': each App has an own unix user and if this flag is set, the user can login with SSH for debugging
* ''App Store URL'': the URL to the App Store where Apps are searched and also an update of the AP image itself
* ''Devices app URL'': the URL to the Devices App to manage the AP through Devices
* ''Devices app URL 2'': don't use!
* ''App Platform DNS name'': currently not used
* ''NTP server 1/2'': NTP servers for this AP (in addition to NTP servers retrieved by DHCP)
* ''Timezone string'': A timezone string which is used by the App Platform Manager to do certain jobs according to the configured timezone.
** Note that this doesn't change the timezone of the linux itself!
* ''DNS server 1/2'': DNS servers for this AP (in addition to DNS servers retrieved by DHCP)
* ''Database optimization time'': The database optimization process will be started at this hour (local time), with a random offset of up to 7 hours
* ''Command file'': see [[#Backup_of_the_Apps| Backup of Apps]]

== Security ==
* ''Current Webserver certificates'': shows the current certificates with the ability to download them.
* ''Webserver certificate'': upload a webserver certificate in PEM format
* ''AP Manager password'': the password to the web interface of the AP Manager (normally set through Devices)
* ''Linux root user'': password of the root user (normally set through Devices)
* ''Linux admin user'': password of the admin user (normally set through Devices)

== Let's Encrypt ==

Configure the certificate creation by Let's Encrypt here.

* ''Enable'': turns the automatic creation on or off
* ''Let's Encrypt App URL'': the URL of your Connector for Let's Encrypt App Service. You can copy&paste this URL from your Connector for Let's Encrypt PBX Manager Plugin
* ''Let's Encrypt App Password'': the client password of your Connector for Let's Encrypt App Service. You can copy&paste this password from your Connector for Let's Encrypt PBX Manager Plugin
* ''Key length'': 2048, 3072 or 4096 (keep in mind, that [[{{NAMESPACE}}:Certificate_management#Certificate_Key_Length_and_CPU_Usage|a higher value provides higher security but also lower performance!]])
* ''DNS Name'': the external DNS names of your device (up to 100 possible)

== Alarms and events ==
* ''URL'': URL to the Events app
* ''Username/Password'': HTTP credentials of the Events app
* ''Email address'': an email address which will get emails on full disk alarms/warnings
* ''Threshold'': All Apps will be stopped and an hourly email sent on reaching this threshold. An alarm is generated 10% before reaching this threshold and an email is sent every 24 hours.

== SMTP ==
SMTP server settings for sending emails from within the AP Manager.

Starting with 16r1 you also can configure OAuth2 Authentications. You can have a look into our HowTo Article for assistance: [[Howto16r1:Configure OAuth2 E-Mail]]

== Replication ==
App Platform [[#App Platform replication|replication settings]]

== Registered Access Domains ==

== Update ==
Updates the App Platform to the latest image available on the App Store.

== Restart ==
Restarts the App Platform.

== Shutdown ==
Shuts down the App Platform.

= App Platform replication =

== Requirements ==

* 13r3 or above on both standby servers and the primary server
* at least an App Platform image starting with version 110002 (otherwise postgresql is too old)
* standby and primary servers must have the same system architecture
** arm gateways (IPx11) just with arm gateways (IPx11)
** arm64 gateways (IPx13) just with arm64 gateways (IPx13)
** x86_64 virtual machines just with x86_64 virtual machines
* the disk size on standby servers must be at least equal as the disk size on the primary server

== General ==
The configuration is done within the App Platform Manager next to the settings button under "Replication".

=== Off ===
No replication is done at all.

=== Primary ===
The App Platform acts as primary server for one or multiple standby servers. 
Max 8 standby servers can be configured. 
 
Every standby server must get a unique name on the primary server which is then also configured on the standby server itself. This is due to the fact, that the primary server preserves data for every standby server while it's not reachable. 
A standby server name must be a valid domain name, although this name is currently not used as DNS name (but might be used in the future). 
 
The password is randomly pregenerated and must be used as handed by the App Platform Manager.

==== PostgreSQL port ====
The default PostgreSQL port is 5432 and can't be changed on the primary. It must be reachable through your firewall or at least forwarded on a different port towards this App Platform on port 5432.

=== Standby ===
Configure the password from the primary and one of the not yet used standby server names. 
The host and port must be reachable through the network. You can specify a non default port which then must be forwarded somewhere else to port 5432 on your primary.

*Note: Do '''not''' configure the same standby name on different standby servers, as this will break the replication on at least one standby! 
*Note: On a standby, all '''locally installed apps are removed''' during installation

== Failure detection ==

The replication state on both primary and standby servers are continuously monitored. 
In case of a broken connection, an alarm is triggered at once and just cleared if the failure goes away. 
 
If such an alarm lasts for 5 minutes an email is send. The recipient address must be configured in the App Platform Manager settings under "Alarms and Events" and you must also provide a valid SMTP configuration.

== Failover ==

There is no automatic failover procedure. If you detect the failure state, you must get active yourself.

=== Standby down ===

Fix the standby server and see if the replication comes up again. If not, setup a new standby server which will replicate the whole database cluster from scratch.

=== Primary down ===

If the primary is down and cannot be brought into life again, you must take the following steps, depending on your configuration:

==== One standby server ====

* Disable the replication in the replication configuration. You will then have a standalone App Platform afterwards.

==== Multiple standby servers ====

* Change the replication type on one of the standby servers from standby to primary. Please note that the other standby entries must still exist here (they are automatically offered)!
* Change the host entry on the other standby servers to the new standby server. The standby server will sync the whole database cluster again, which will take time.

==== Configuration changes ====

You must also tell the PBXes and other tools to use the new primary server.

* You may simply change the IP address behind the DNS of your primary server to point to the new primary server.
**Note: to ensure rapid recognition of the new DNS target, the definition of an appropriate TTL value is recommended
* Without DNS, you must currently modify the configuration by replacing the IP address of the old primary with the new address.
** This must be done in every master PBX configuration.
** This must be done in every App configuration which may use this IP address, e.g. Devices which rolls out an alarm server configuration

== App Platfom update ==

If you're running an active standby server and the major version of the PostgreSQL database didn't change, you can simply update primary and standby servers independently. 
 
If it contains a ''new major version'' of the PostgreSQL database, you must follow these steps:

* deactivate replication on all standby servers (which promotes these standby servers to active servers)
* ensure that the '''same''' App Platform Manager version is running on primary and standby servers!
* perform the App Platform update on the primary server
* perform the App Platform update on the standby servers
* reactivate replication on the standby servers (which will do a full replication again, so it might take some time)

Alternativly you may setup the standby server from scratch directly with the new App Platform image version.

Sadly there is currently no better method offered by PostgreSQL to perform such an upgrade.

See also https://wiki.innovaphone.com/index.php?title=Howto14r2:Firmware_Upgrade_V14r1_V14r2#App_Platform_and_Apps

== Technical backgrounds ==

=== Streaming replication ===

We use the asynchronous [https://www.postgresql.org/docs/9.3/warm-standby.html#STREAMING-REPLICATION streaming replication of PostgreSQL]. A transaction thus just waits for a commit on the primary server. Standby servers will receive the transaction asynchronously afterwards to avoid a reduced writing performance. 
A primary server keeps the neccessary WAL files for every standby server until the standby fetched the neccessary information. 
This fact can lead to higher disk space usage on the primary if one or multiple standby servers are offline for a while.

Take care to fix broken replications as soon as possible to avoid a full disk on the primary server!

=== What is replicated ===
The whole database cluster of an app platform is replicated. This includes every database of every instance and the database of the App Platform Manager itself. 

=== App Services on standbys ===
The database of the App Platform Manager itself also contains the App service binaries to be able to restore applications in a failover case. 
You do not have to install App services on the standby if you install them on the primary. 
App Platform Manager and Webserver can be updated as usual through the App Store or the Devices App if the standby is connected to Devices.

=== App Platform Manager configuration of the standby server ===
The App Platform Manager configuration of the standby server cannot be stored inside the database, as the database is readonly. So it is stored inside a configuration JSON file under ''/home/root/standby.conf''. 
This configuration is backed up as usual by a Devices backup job and can be also manually restored on a standby (not on a primary though!).

Configuration options from the primary are not synced to the standby server, as the standby server has its own configuration (as it could be in a different network etc.)!

=== No automatic failover ===

There is currently no automatic failover mechanism. PostgreSQL doesn't offer multi master replication, so writing is just possible on the primary itself. Standby servers have a readonly database. 
Let's consider the following use case if we would implement an automatic failover with the current technical possibilities: 
* The primary server is connected to a master PBX.
* A slave PBX is also connected to the primary server in another location.
* A standby server is in this location and replicates from the primary.
* The internet connection between primary and standby fails.
* The standby promotes itself to primary, so that the master PBX now writes to the old primary and the slave PBX now writes to the "new" primary.
* The internet connection comes up again and both primary and standby servers now have databases which are out of sync and which cannot be merged.

=== Security ===

* port 5432 must be reachable on the App Platform
* For every standby a PostgreSQL user is created with the REPLICATION role on the primary. Just this user has access to the database server from non localhost connections.
* You cannot establish a standard connection with such a user and modify/read from tables.
* The replication connection is established over TLS by default.

= App Installer PBX Manager Plugin =
== Requirements ==

* V14 and above

== General ==

The app installer plugin allows IT administrator (with access to the PBX Manager) to install/update/delete new apps from the innovaphone app store including Partners apps. It is automatically available with existing app platforms or after adding a new one in the PBX Manager.
It offers a view to the App Platform Manager‘s App Store with all the available functionalities and simplifies the install, update and uninstall of apps.

== Dedicated AP for each user ==

Installing a new app will install the app service and add a new instance with the user’s domain. The instance is automatically started. 
This further enables the configuration of the instance through its respective PBX Manager plugin. 
Uninstalling the app will remove the app service and the corresponding instance.

== Shared AP between users ==

Installing a new app works in a similar way to that of the dedicated AP. However, each time a new user installs the app, only a new instance is created if the app service is already installed. 
A user can uninstall the app, in this case the corresponding instance is deleted. If no more instances exist, then the app service is uninstalled. 
The administrator can only update the app service in such scenario.

= Known Issues =

== Reboot after an image update hangs (ARM/ARM64 gateway) ==

If it happens, that the App Platform doesn't recover after the reboot, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
If '''Kernel command line''' is set to '''/dev/ram0''', the App Platform booted the ramdisk. 
 
Try to fetch the upgrade log file:
https://[APP-PLATFROM-IP/DNS]/manager/ramdisk.log
 
If this doesn't work, try to login with putty in this case (default credentials admin/ipapps and root/iplinux) and issue this command: 
''cat /apps/install_step1.log'' 
 
If this file contains '''finished''' at the end, you can reconfigure the settings under App Platform -> General: 
* press '''Stop'''
* Initrd file: empty
* Kernel command line:
** IPxx11: '''root=/dev/sda3'''
** IPxx13: '''root=/dev/nvme0n1p3'''
* Ramdisk size: empty
* press '''Start'''

The App Platform should boot and run the already updated image.

<pre style="color: red; font-size:150%;">---WARNING---
If the file doesn't contain "finished" at the end, you may still need to wait, as an upgrade may take some time!
Do not reconfigure without being sure that the upgrade has finished, otherwise your system may won't run!</pre>

== Reboot after an image update boots always into rescue mode (virtual machine) ==

This most likely means that the image installation didn't finish the first time and was interrupted before the bootloader settings could be changed back to the default partition. 
 
If your App Platform doesn't boot or isn't normally accessible after manual selection of the standard entry in the boot menu, you need to '''revert''' to a '''snapshot/backup''' prior to the update. 
If your App Platform runs normally though, you can follow this instruction to change the default boot entry: 
 
* boot into the '''rescue''' partition
* login with root/iplinux
* edit the file /boot/grub/grub.cfg
** search the line with '''set default=0''' and change it to '''set default=1'''
** reboot

== App Platform doesn't start after an update ==

=== Gateway ===
If it happens, that the App Platform doesn't want to start an update, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
* '''Shutdown''' the App Platform and '''Stop''' it 
* Set '''Kernel command line''' to '''/dev/ram0''' 
* Set '''Initrd file''' to '''ramdisk.ext2.xz''' 
* Set '''Ramdisk size''' to '''100000''' 
* '''Start''' the App Platform now. 

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

Note: This process can take a while, after it's finished it reboots and automatically change the '''Kernel command line''' value.

=== Virtual Machine ===

Boot into the '''rescue''' partition.

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

=== It still doesn't start ===

If it still doesn't start, configure the App Platform to boot from /dev/sda3 (or inside a VM start the second boot loader entry) and login with SSH as root.
Then do a first check to verify that you have a specific error due to an incomplete update or a [[Howto15r1:Firmware Upgrade V14r2 V15r1#AP Upgrade to Image 130006|wrong update order]]:

* /etc/init.d/S92manager stop
* /apps/manager/manager
* if this outputs '''error while loading shared libraries: libcrypto.so.3:''' you have a manager version which cannot run on the current image.

In this case you must download an older build (14r1 1410593):

* /etc/init.d/S92manager stop
* wget --no-check-certificate -O /apps/manager/manager https://webbuild.innovaphone.com/1410593/arm/manager/manager
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* wget --no-check-certificate -O /apps/webserver/webserver https://webbuild.innovaphone.com/1410593/arm/webserver/webserver
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* chown root:root /apps/manager/manager
* chown root:root /apps/webserver/webserver
* chmod +x /apps/manager/manager
* chmod +x /apps/webserver/webserver
* echo 110000 > /mnt/sda1/label
** this allows the manager to perform an image update again
* /etc/init.d/S92manager start
* now perform an image update and '''afterwards''' update your apps again

== Webserver doesn't respond after an image update ==

If you can't reach the web UI after an image update, please try to connect with SSH as admin user and delete old coredumps, which may prevent the App Platform Manager from starting correctly:
* su root (become root)
* rm -f /mnt/sda2/log/core_dumps/*/*
* /etc/init.d/S92manager restart

Check if you can now reach the App Platform again.

= Tracing =
Each App Service has its own log file, which can be accessed through the Manager App. You can configure a log file size for each App Service. 
Each App Intance has its own trace flags. The following trace flags can be set: 

* Alarm client: used by the manager to send alarms to an alarm server
* App: logs from the App Service itself
* App WebSocket: logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
* AppSharing: just native clients
* AppProxy: just native clients, logs requests which are proxied between the local webserver and the remote server
* Audio: just native clients
* Browser: just native clients
* Command: the command interface is used to execute shell commands, e.g. used by the manager App
* Config: logs config changes of an App
* Database: database logs
* DB files: database file logs
* DNS: DNS request logging
* DTLS: just native clients, DTLS request logging
* Ethernet: interface to get ethernet adapater infos, just manager App
* File: logs for file system access (synchronous), e.g. manager App
* Files: logs for file system access (asynchronous)
* HTTP client: http client logs
* HTTP file: logs for static HTTP files
* ICE: just native clients
* LDS: local domain sockets
* Media: just native clients
* Media channel: just native clients
* Process: IProcess interface logs which is used for spawning, killing processes etc.
* SMTP: SMTP client logs
* TCP: TCP logs
* Time: ITime interface logs
* TLS: TLS logs
* TURN: just native clients
* UDP: UDP logs
* Video: just native clients
* WebSocket client: logs outgoing websocket connections
* Webserver traffic: logs incoming HTTP traffic, which is forwarded from the webserver to the App
* WebDAV service: logs WebDAV requests to the App
* Webserver: enables webserver specific logs

== RPCAP ==

If you open the Manager App, click on the Manager in the left list and then on the Diagnostics button, you can enable RPCAP. 
You can add the interface in wireshark with the string:
rpcap://<APP-Platform-IP>/eth0

'''Please don't forget to disable RPCAP after your testing!'''

= How-Tos =

== How to retrieve files from the App Platform ==
To retrieve files from the App Platform which can not be retrieved via the App Platform manager UI, you can connect to the App Platform using the SCP protocol on port 22. 
 
First copy files to /home/admin as root with Putty or another SSH client:
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''su root'' to be root (''iplinux'' as default password)
 
You can now copy files to ''/home/admin'' (e.g. from /var/log/apps/manager/...). 
 
You can create a tar archive with all logs like this:
* cd /home/admin
* tar -cf - /var/log/* | xz -z - > log.tar.xz
** you may want to exclude coredumps (due to their size):
** tar -cf - --exclude=/var/log/core_dumps/* /var/log/* | xz -z - > log.tar.xz
* chown admin:admin /home/admin/log.tar.xz
 
Then copy the files to your local system, e.g. with WinSCP 
* use ''SCP'' as protocol (NB: WebDAV is not supported on most of the directories on the App Platform )
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''/home/admin'' as start directory
* copy the needed files

== App Platform disk space warning ==

If the configured threshold is reached, all Apps are stopped inside the App Platform . You must then free disk space somehow.

=== Find large instances ===
Click through your apps in the tree on the left side and take a look at the database size of each instance.

=== Delete data inside an instance ===
It depends on the type of app if you can delete data or not. E.g. you can start the Files app and delete files inside this app. 
This won't reclaim disk space though due to the way how PostgreSQL databases work, so you need to follow this guide to reclaim the disk space:

* start the corresponding App
* delete data inside the App
* optimize disk usage of the database by cliking on the button "Clean up database" under Edit instance. If this does not help, continue with the following steps.
* stop the corresponding App again
* download a backup of the instance (backup button at the top), this backup contains the whole instance data, also the password of the instance
* delete this specific instance
* restore the downloaded backup (restore button at the top)

Depending on the hardware and the size of the instance, this process may take hours to complete!

=== Resize the disk ===
The resizing of a disk is just possible for virtual machines, see [[#Resizing the disk of a Virtual machine|Resizing the disk of a Virtual machine]].

=== Delete the whole instance ===
If there is no other possibility, you can delete the whole instance. Afterwards you recreate the instance with the same values and a new random password. Don't forget to set this password in the corresponding PBX App objects though!

=== Restart the Apps or the App Platform ===
If you have enough disk space again, you must either restart the whole App Platform or you manually start all Apps again.

== App Platform/Apps app not online anymore due to full disk ==
If the apps app is not online anymore and you can't access any apps anymore, try to login with an SSH client to see if your disk is full.
Login as admin and afterwards as root (su root). 
 
* issue '''df -h''' and see the disk usage of /dev/sda2, if this is 100%, your disk is too full
* stop the manager
** /etc/init.d/S92manager stop
* empty the 500 MB file, which is exactly for this case here (manager must be 13r1 SR9 or higher to have this file)
** echo "" > /mnt/sda2/empty_if_no_space
* delete log files to recover some space
** rm /var/log/apps/*/*
** rm /var/log/core_dumps/*/*
* restart the postgresql server (see the output if this worked or not)
** /etc/init.d/S50postgresql restart
* restart the manager
** /etc/init.d/S92manager restart
* wait until everything is online again
* open the Apps app and try to find the instance which uses the most disk space and try to delete files/content from it
** you may want to stop all app services first to prevent more writes to the database
** if not possible, you can delete this instance, but you'll loose all data from this instance then!
* after that you can try [[{{NAMESPACE}}:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files|Reference14r2:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files]] to free up space
** If this does not work you can create a backup from the database, delete the database and import the database again.
* free up at least 500 MB so that the manager can create the file again
* delete /mnt/sda2/empty_if_no_space if you are done and restart the manager:
** rm /mnt/sda2/empty_if_no_space
** /etc/init.d/S92manager restart
** the manager restart automatically recreates the empty_if_no_space file if this file doesn't exist

Make sure, that you do '''not''' have backups configured to a local files instance while this files instance is not excluded from backups.
An instance can be excluded from backups in the instance settings in the App Platform Manager.

If all of this doesn't help, you can resize the file system on a VM:
* proceed with [[{{NAMESPACE}}:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine|Reference14r2:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine]]

== Resizing the disk of a Virtual machine ==

Do '''NOT''' resize if you're running an App Platform version higher than '''110000''' and lower than '''110027''' or '''130007''' and lower than '''130015''' or your data will be lost!
Please update your App Platform to version 130015 or higher before you start resizing your disk.

* stop the VM
* expand the disk using your VM utilities
* start the VM and boot from the first boot entry '''rescue/setup'''
* login with '''root''' and '''iplinux'''
* execute this command: '''/home/root/install_step1.sh log.txt resize'''
* the VM reboots automatically after a successful resize

== Shrink the physically size of PostgreSQL database files ==
Tuples that are deleted in your database are not physically removed from the database-file. So the claimed space on the harddisk is still in use after the delete operation.
If you need to free up some disk space you can force to reorganize the physically database-file on your harddisk.

You can also start this process through the instance settings as long as the App Platform Manager is still running.

'''Important: You are operating on the Database, you have to make a Backup of your Database before you do this!'''

Login via SSH to the APPlatform with the ''admin'' User
su root

=== All databases ===
/etc/init.d/S92manager stop # not always needed, but in case of database errors recommended, of course no app is online then
sudo -u postgres reindexdb -a
sudo -u postgres vacuumdb -a -f
/etc/init.d/S92manager restart # just execute if the manager has been stopped above

=== single database ===
sudo -u postgres reindexdb -d dbname # for a single database with dbname
sudo -u postgres vacuumdb -d dbname -f # for a single database with dbname

Note: This may take some time and the App database is not available during this time

After the process you can check the free dispace via <code>df -h</code>. You can check the claimed space from the database file with the command <code>du -sh /mnt/sda2/pgsql/</code>.

== Change IP Addresses / DNS Names / System Name ==

If you want to change the System Name or the DNS Name of the PBX and/or App Platform Platform you must change records manually '''in the described order'''!
You have to know the Admin password to directly Login to the App Platform .

=== App Platform ===
; Settings - General
* ''Devices app URL''
* ''App platform DNS name''

; Settings - Alarms and Events
* ''URL''

; All Instances
* ''Domain''
* ''Webserver path''

=== PBX ===
Download the configuration and ''search/replace'' in the config file. Upload the config file and reboot.

Manual:
* ''URL'' in all PBX Object (Apps, Voicemail ...)
* [[{{NAMESPACE}}:Gateway/CDR|CDRx]]
* [[{{NAMESPACE}}:PBX/Config/General|IP address for App Platform]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reset Password Page]]
* [[{{NAMESPACE}}:PBX/Config/Authentication|Verification link]]

Depending on your change you have to activate/deactivate the Setting [[{{NAMESPACE}}:PBX/Config/General|Operation without DNS]]

=== Additional Devices / Steps ===
* ''Devices Registration URL''
** There is no automatism to change the URL on all devices in your setup.
** If you have the option to use DHCP, you can temporarily overwrite the [[{{NAMESPACE}}:Services/Update|Update URL]] and execute a [[{{NAMESPACE}}:Concept_Update_Server|custom update script]] to change the ''Device Registration URL''
* ''Alarm server''
* Reverse Proxy configuration
* Change ''Domain Name'' in Devices if you have also changed the system name

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

initial error at 1500329378: ext4_journal_start_sb:328
last error at 1500329378: ext4_journal_start_sb:328

Or you get events like "Broken file system" from your App Platform .

This indicates a file system failure on the Linux Installation.

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

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

=== Gateway ===

* Open the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the Kernel command line from root=/dev/sda3 (or /dev/nvme0n1p3) to root=/dev/ram0
** modify the Initrd file to ramdisk.ext2.xz
** modify the ramdisk size to 100000
** start Linux again
:: This will run Linux on another (hopefully sane) partition.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code> on IPx10/IPx11 gateways
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code> on IPx10/IPx11 gateways
** on the command prompt, use <code>e2fsck -p -f /dev/nvme0n1p2</code> on IPx13 gateways
** on the command prompt, use <code>e2fsck -p -f /dev/nvme0n1p3</code> on IPx13 gateways
:: this should fix any issue on the file system

* go back to the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/ram0'' to <code>root=/dev/sda3</code> (IPx10/IPx11) or to <code>root=/dev/nvme0n1p3</code> (IPx13)
** clear the Initrd file field
** clear the ramdisk size field
** start Linux again
:: This will run Linux on the original partition.

=== VM ===

Restart the VM and select the first entry in the boot menu from grub.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system
* Reboot your VM
[[Category:Concept]]

== How to create a memory dump of a running process ==

Sometimes it's usefull to have a memory dump of a running process to investigate certain issues.

* login with SSH and become root
* find out the PID of the relevant process, e.g. with ''ps aux | grep /apps/manager/manager | grep -v grep''
* gdb --pid PID -ex gcore --batch
* this creates a core file core.PID
* download this core file with WinSCP or similar tools

== Move instance database to external database host ==

In case you want to use an external database server instead of the integrated:

* download a backup of the specific instance over the App Platform Manager
* create a postgresql database on the external host:
** createdb --encoding=UTF-8 exampledb
* restore the backup
** pg_restore -d exampledb backup-exampledb.dump
* change the ownership to a specific postgresql user (which you have to create yourself first)
** psql -d postgres -c "ALTER DATABASE exampledb OWNER TO exampleuser"
* configure the database host, name, user and password on the instance inside the App Platform Manager

Reference15r1:Concept App Service Devices

2026-05-05T06:20:36Z

Dde: /* Certificates configuration */

[[Category:Concept|Apps]]
The App Service Devices is an App Service which can be installed on an innovaphone App Platform. It is used to administrate the innovaphone devices which belong to the whole installation.
== Applies To ==

* innovaphone PBX from version 13r1

== Apps ==

=== Devices App (innovaphone-devices) ===
This is the standard UI App for Devices.

Parameters:

;Websocket: to publish the com.innovaphone.devicesui-API, which can be used to link directly to devices (which is done e.g. inside the Events app)

=== Devices API (innovaphone-devices-api) ===
This is a hidden App, which provides the Devices API (com.innovaphone.devices). This API can be used to find and communicate with devices which are registered to the Devices App.

Additionally it acts as a provider of the Search API (com.innovaphone.search). So you can find devices and domains in other apps like the Search App.

Parameters:

;Hidden: DevicesApi must be a hidden App
;Websocket: to get the URL of the Devices App itself which is used for provisioning

== PBX Manager Plugins ==

=== Devices ===

With the Devices plugin App objects can be created, edited and deleted for Devices and the Devices API on the PBX.

== Concepts ==
All innovaphone hard phones and gateways starting from version 13r1 can establish a registration inside the Devices App and therefor administrative tasks can be performed through the App.

=== Domains ===

In a hosted environment, it might be needed to add multiple domains to the Devices App. 
After the initial installation of Devices through Install, you have administrative rights and can add more domains.

==== Administrative rights ====
You have administrative rights if the configured PBX App object for Devices uses the password of the instance which is configured in the Manager App and the PBX uses the same domain as this instance.

==== Domain local rights ====
You have just rights to a certain domain if the configured PBX App object for Devices uses the domain password which can be configured in Devices for each domain and the PBX uses the same domain name as configured in Devices.

==== Assign rights to other domains ====
Domains can gain access to other domains by configuring these access rights in the Devices App.

==== Deploy passwords and access rights ====
During install, a domain is created inside the Devices App. There is a checkmark Deploy the domain password on all devices which is set by default and which is the same as the administrative password.
If you change the domain password, all passwords on all administrative devices and app platforms which are connected to this domain will be also changed. 
Since 13r2sr25/13r3sr7/14rx: devices which are auto provisioned or provisioned through the Profile/Users Admin App will get a random password instead of the domain password.
If you add a phone device manually to a domain inside the Devices App, this phone device will also get a random password. Other device types added manually or devices added with a provisioning code which has been created within the Devices App directly, will get the domain password instead. 
 
This will also set the manager password and the SSH passwords of App Platforms. 
 
The clear text random passwords can be requested and viewed in the settings of a device in the Devices App.

Attention: If you untick the '''Deploy administrative devices passwords''' checkmark, the password won't be deployed anymore, but also not reconfigured to the default password!

Attention: After each reconnect of a client, the password will be deployed again.
This means, if the checkmark is set and you set another password somewhere else (e.g. under General::Admin),
this password will be just valid until the next reboot or reconnect to the Devices App!

;Create new random passwords
You can rollout new random passwords by unticking the '''Deploy administrative devices passwords''' checkmark and ticking it again. 

;Devices with multiple domains (Cloud)
In a hosted environment, you can use the Devices App with multiple domains. The corresponding instance of Devices has a configured domain and an instance password set inside the manager. 

The hosting PBX has a domain inside Devices with a specific password. 
If this domain name matches the instance domain of the Devices instance and the password matches either the instance password or the domain password, you will be logged in as admin and have access to all domains. 

Each newly created domain has its own password inside Devices. If you create an App Object inside a PBX with this domain and the password of this domain (inside Devices), you will just have access to this single domain. 

Devices also has the possibility to grant access to other domains for a specific domain.

=== Categories ===

There are two types of categories:
* provisioning category: used for device configurations and provisioning
* standard category: used for update/backup jobs and device management

Each device can have just a '''single''' provisioning category, as it receives it's configuration by all configured device configurations for this provisioning category.

In addition, a provisioning category, which is used inside an analogue phone/phone device configuration '''cannot''' be used to provision a gateway.

=== Device connections ===
The Devices registration is done through a websocket connection to the webserver of the App Platform and the Devices instance (standard HTTP/s port). 
The URL used can be configured manually under [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:General/Devices_Registration Devices Registration] or through a new provisioning mechanism. 
 
A binary protocol is used to transfer information between the device and the devices App. The MAC address is the unique key to identify a device. 
 
If a device is added to a domain in Devices, the device gets a unique random password. Without such a password, a device shows up as '''unassigned''' in the Devices app.
This is also the case after a long reset or when the device lost its configuration. 
 
In such a case, the device has to be manually added again to a domain or it has to be provisioned again.

If a device is not assigned to a domain or provisioning category, it won't receive any configurations.

==== Devices Registrations ====
See [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:General/Devices_Registration Devices Registration]

==== Second Devices Registration URL ====

The firmware has a second SYSCLIENT2 module, which can be configured to point to a different Devices instance and the AP Manager also has a second Devices Registration URL. 
 
If you use this configuration option, you should take care and consider:

* if the Devices domain from the second configuration provides a password for all devices, the password is ignored, as it would lead to inconsistend passwords otherwise (from 13r1 SR12 on)
* the Devices domain from the second configuration should not provide Devices Configurations or Update Jobs as these might collide with configurations from the first Devices instance!

Generally, only one of the two ''Devices'' App instances connected to the device must apply changes to the device.

We strongly discourage the usage of this second configuration option due to unexpected behaviour if incorrectly used!
Never use the second URL if you use software or hardware rental!

==== Device information ====

The following data is transferred:
* MAC address
* device type (e.g. IPVA, AppPlatform, IP112)
* IP addresses (IPv4, IPv6)
* version (not searchable)

You can also search for this data inside the devices tab in the App.


=== Provisioning ===
Devices can be added by provisioning (both phones and gateways).
The standard online provisioning looks like this:
* a user or administrator creates a provisioning code in the Devices or Users App (this stores the Devices URL on the provisioning server side)
* a device with 13r1 or newer is connected to the network after a long reset
* the provisioning code has to be entered within one hour (after one hour, the Update URL isn't polled anymore)
* the device sends this code to config.innovaphone.com and retrieves the Devices URL
* the device connects to the Devices URL and is added to the domain where the code has been created

There is also an [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Offline_Provisioning offline provisioning mode]. 
There is also an [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Provisioning#Automatic_provisioning automatic provisioning mode].

Note: provisioning is cancelled if the device already belongs to another domain in the same Devices instance! This prevents the unauthorized move of a device between different domains.

==== Devices Registration URL ====

The Devices Registration URL which is set through the provisioning process, always starts with '''wss'''. This is not dependent anymore on the App URL which is configured inside the PBX Devices App object.

=== Updates ===
The Devices App can be used to rollout updates. 

==== JSON files ====
The update files have to be acccessible on a webserver without authentication and four json files are used:
* firmware.json: innovaphone device firmware
* apps.json: Apps for the App Platform
* software.json: contains software for DECT handsets
** just IP64 and IP65 are used and supported
* phoneplatform.json: contains the phone platform image for e.g. the IP270

You can either use the standard innovaphone App Store for these files or your own local webserver. 

==== Update jobs ====
You can configure several update jobs with different categories to organize your updates. 
Update jobs are always sequentially processed and inside one update job, just '''20''' devices are updated at the same time.

==== Device update check after the update job has been already executed====
If a device goes online, the newest suitable update job is searched for this device (depending on the categories). 
If an update job is found, the update is just performed, if there has been '''no''' successfull update for this device in this job before and the version does not match (simply string compare).

====Update errors====
If an update fails, the Devices App shows an error. You may have to enable further tracing on the updated device itself to find out the reason of the failure. 
 
* on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0 module and take a look at the events which may already tell you the reason
* on an App Platform, enable the App and HTTP Client trace flag on the manager

An update job is retried '''two''' times if updates inside this job failed. The retry is done '''ten''' minutes after the update job finished previously.

====innovaphone myApps====
The path to the App Store and the used innovaphone myApps version is updated to the version of the gateway on gateways with an enabled PBX after a successfull update. 
This configuration can be found [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:PBX/Config/myApps here]

Inside the configuration on an update job, the flag "Do not update myApps launcher software" disables the update of the innovaphone myApps version inside PBXes.

====DECT handsets====
If you check the update DECT handsets checkmark, all DECT devices will be configured to rollout updates to DECT handsets. 
See [[{{NAMESPACE}}:Concept_App_Service_Devices#Supported_DECT_handsets | Supported DECT handsets]].

The DECT handset firmware will be searched inside the configured software.json.

=== Backups ===
The Devices App can be used to backup the configuration and data of Apps and devices. 

====Webserver requirements====
Backups are stored on a webserver with or without Digest/Basic authentication and with the '''webdav PUT''' method.

====Backup jobs====
Backup jobs are executed sequentially. Inside one backup job, just '''20''' backups are performed at the same time.

====Phones or gateways====
The configuration file is stored. Therefor the Devices App tells the device to store the configuration with a !mod cmd UP0 /sync prot URL.

====Apps on an App Platform====
The databases of all existing instances and the manager are stored. 
Each installed App Service can have multiple instances and each App instance has its own database. 
A database contains '''both''' configuration and data of an App instance! 
The manager database contains the webserver certificate and further manager related configuration settings.

The Devices App establishes a websocket connection to the manager and tells the manager where to store the backups. 
The manager on the backuped App Platform itself performs the HTTP requests to store the files.

====Backup errors====
If a backup fails, the Devices App shows an error. You may have to enable further tracing on the backuped device itself to find out the reason of the failure.

* on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0
* on an App Platform, enable the App and HTTP Client trace flag on the manager

=== Restore ===
====Phones or gateways====
Just as always under [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Administration/Upload/Config Upload Config].

====Apps====
The App Service itself has to be installed on the App Platform prior restoring of a single instance. 
The restoring is done in the Manager App on the App Platform itself. 
The instance settings, the configuration and data are restored in a single process.

=== Device Configurations ===

You can define several device configurations. These configurations are either applied to all devices inside this domain or to selected categories. 
Configurations are applied on creation and on every reconnect of a matching device.

==== Transfer checkmarks ====

Some configuration options have a specific checkmark to enable the transfer of the option. 
 
* Checkmark disabled:
** configuration option field(s) are disabled
** option values are '''not''' transferred at all
* Checkmark enabled:
** configuration option field(s) are enabled
** option values are transferred, even if field values are empty

==== Expert configuration ====

The expert configuration can be used to configure different settings which are not available inside the other device configurations. 
You can use the standard syntax of an update server script (see [[ {{NAMESPACE}}:Concept_Update_Server | Concept Update Server ]] for a general overview and the section on [[Howto:PHP_based_Update_Server_V2#Hints_for_writing_your_update_snippets | Hints for writing your update snippets ]] (note that the remainder of this article relates to the now deprecated old mechanism, so please disregard the rest)). 
 
Some hints:
* the expert configuration is just executed once after a device restarted and on change of the expert configuration itself
* the expert configuration is executed after all other device configuration types, so that you can override changes
* to make configuration changes effective, you may also need to issue a final ''config write'', ''config activate'' and ''iresetn'' command (see the [[ {{NAMESPACE}}:Concept_Update_Server#Check_command | ''check'' command]] for details)
* some commands shouldn't be used inside the script:
** [[ {{NAMESPACE}}:Concept_Update_Server#Times_command |''times'']]: since the expert configuration is executed only once after a reboot of the device and when changes are made, it does not make sense to use the ''times'' command
** [[ {{NAMESPACE}}:Concept_Update_Server#Prot_command |''prot'']]|[[ {{NAMESPACE}}:Concept_Update_Server#Boot_command |''boot'']]: use an update job instead
** [[ {{NAMESPACE}}:Concept_Update_Server#Scfg_command |''scfg'']]: use a backup job instead
** [[Howto:PHP_based_Update_Server_V2#Using_vars_create|''vars create'']]: this cmd will always raise the ''reset needed condition'' and the aforementioned ''iresetn'' command would always execute therefore. As a result, the devices would enter a boot loop. Be sure to avoid this using an appropriate [[ {{NAMESPACE}}:Concept_Update_Server#Check_command |''check'' command ]] and update its ''<serial>'' properly whenever the expert configuration is changed

==== Certificates configuration ====
You can use this configuration to rollout certificates to the trust list of your devices. 

* Manual upload certificates.
* Configure up to five URLs which are polled every 24 hours. They must return files with PEM formatted public keys (one or more) which are then rolled out.
** certificates are just rolled out if differences are determined, so if URLs are polled and no changes are detected, certificates are not rolled out again. Changes are detected by fingerprint comparison of each embedded certificate
** if a device restarts, the configuration is applied again. Just the fingerprints of the device trust list are checked against the configuration trust list and just on differences, certificates are rolled out again
* Configure https://download.innovaphone.com/certificates/innovaphone.pem to always have the innovaphone public keys in your trust list (e.g. used for our push service).
* Configure https://download.innovaphone.com/certificates/ca.pem to always have the innovaphone Device Certification Authority certificates in your trust list.
* Configure https://download.innovaphone.com/certificates/ca-unverified.pem to always have the innovaphone Unverified Device Certification Authority certificates in your trust list.
** The Unverified CA is used for non hardware devices, e.g. IPVAs, which are not shipped with an official innovaphone Device Certification Authority certificate, as innovaphone has no control over the serial number here.

Using this configuration, the trust list can only be managed through ''Devices'' because it is cleared before each rollout.

==== DECT Handsets ====

This configuration can be used to configure specific options like language, voicemail number etc. for DECT handsets. 
 
* all DECT devices like IP1202, IP1203 etc. will receive this configuration (of course just if the configured categories match)
* Devices configures a URL like https://domain.com/domain.com/devices/parameters/id.xml on the specific DEVMANBW module.
* This file is then polled by the basestations and the read values are transfered to the DECT handsets.
* see [[{{NAMESPACE}}:IP1202/IP1203_DECT_System#Configuration_of_Handset_parameters]]

See [[{{NAMESPACE}}:Concept_App_Service_Devices#Supported_DECT_handsets | Supported DECT handsets]].

=== Software rental ===
Regarding the Software Rental program and the Payment Method, please refer to:
* [[{{NAMESPACE}}:Concept_Software_Rental|Concept Software Rental]]

Software rental can be done for innovaphone Cloud installations or for software, which operates on the customer premisis. This could eventually be customer owned hardware or a privat virtual machine, managed by the customer.

==== Hardware licenses ====
Hardware licenses have to be bound on the specific device in my.innovaphone itself and currently can't be handled within the Devices App itself. So you also need to download the licenses from my.innovaphone and upload them on the device with the already known methods.

===== Hardware licenses with software rental =====
If your device has software rental licenses, you can bind hardware licenses within my.innovaphone in the software rental project itself.

===== Hardware licenses without software rental =====
If your device does not have software rental licenses, you should bind hardware licenses in a separate non rental project in my.innovaphone.

==== innovaphone Cloud ====
Inside the innovaphone Cloud, you just have to upload your activation keys with iSCs to add licenses to one or more gateways. 

==== Email expiry notifications ====
You will receive an email notification if the rental of a project expires. This notification will be sent '''seven''' weeks before the expiry and then once a week until the rental expires. 
You can configure one or more email recipients in the domain settings. 
If no email address is configured, the email address of the logged in user account is used.

==== History ====
You can download the history in the Devices App. You'll get a CSV file (semicolon separated). The date and number format depends on the selected language in the UI. 
There is also an API available for automated downloas, which is described [[ {{NAMESPACE}}:Concept_App_Service_Devices#API_to_download_rental_history|here ]].

====Own installation====
Inside your own installation, you have to register a new my.innovaphone account or you can use an existing account inside the Devices App. 
One domain inside Devices belongs to one project inside your my.innovaphone company, so you can handle multiple domains with one my.innovaphone account.

====Technical aspects====
A new rental expiration date is calculated on each license or balance change in the domain. 
So after each change new licenses with a new date are transfered to the gateways and also stored in the Devices App itself. 
If the rental expires, the gateway reboots and the licenses are not available anymore. 
The licenses are also transfered after each reconnect of a gateway to the Devices App. 
 
For license and balance changes, the Devices App must be online and have access to my.innovaphone.com!

====Usage====
You have to add (use the + symbol) a PBX and select all licenses you want to rent. 
Use the '''apply''' button to really bind these licenses. Without usage of the apply button, you can just see a precalculation of the iSCs/month and the rental end date, but nothing is really charged from your balance.

===Change of IP address/DNS name in PBX object===
If the IP address or DNS name inside the PBX object of the Devices App changes, all currently connected clients get a new Devices Registration URL and also all clients, which connect afterwards with the old host name.

== Appendix ==
=== Sample firmware.json ===
<code type="javascript">
{
"devices": [
{ "id": "IP0010", "versions": [ "13r1" ] },
{ "id": "IP0011", "versions": [ "13r1" ] },
{ "id": "IP101", "versions": [ "13r1" ] },
{ "id": "IP102", "versions": [ "13r1" ] },
{ "id": "IP1060", "versions": [ "13r1" ] },
{ "id": "IP110", "versions": [ "13r1" ] },
{ "id": "IP110A", "versions": [ "13r1" ] },
{ "id": "IP111", "versions": [ "13r1" ] },
{ "id": "IP112", "versions": [ "13r1" ] },
{ "id": "IP1130", "versions": [ "13r1" ] },
{ "id": "IP1260", "versions": [ "13r1" ] },
{ "id": "IP150", "versions": [ "13r1" ] },
{ "id": "IP2000", "versions": [ "13r1" ] },
{ "id": "IP200A", "versions": [ "13r1" ] },
{ "id": "IP22", "versions": [ "13r1" ] },
{ "id": "IP222", "versions": [ "13r1" ] },
{ "id": "IP230", "versions": [ "13r1" ] },
{ "id": "IP232", "versions": [ "13r1" ] },
{ "id": "IP24", "versions": [ "13r1" ] },
{ "id": "IP240", "versions": [ "13r1" ] },
{ "id": "IP241", "versions": [ "13r1" ] },
{ "id": "IP29", "versions": [ "13r1" ] },
{ "id": "IP3010", "versions": [ "13r1" ] },
{ "id": "IP3011", "versions": [ "13r1" ] },
{ "id": "IP302", "versions": [ "13r1" ] },
{ "id": "IP305", "versions": [ "13r1" ] },
{ "id": "IP311", "versions": [ "13r1" ] },
{ "id": "IP411", "versions": [ "13r1" ] },
{ "id": "IP6000", "versions": [ "13r1" ] },
{ "id": "IP6010", "versions": [ "13r1" ] },
{ "id": "IP800", "versions": [ "13r1" ] },
{ "id": "IP810", "versions": [ "13r1" ] },
{ "id": "IP811", "versions": [ "13r1" ] },
{ "id": "IPVA", "versions": [ "13r1" ] }
],
"versions": [
{ "id": "13r1", "build": "131705", "text": "13r1 dvl [131705]", "wiki": "" }
]
}
</code>

=== Sample apps.json ===
<code type="javascript">
{
"apps": [
{
"id": "apidemo",
"folder": "apidemo",
"binary": "apidemo",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "Apidemo",
"description": "The Apidemo"
},
{
"id": "appstore",
"folder": "appstore",
"binary": "appstore",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "AppStore",
"description": "AppStore"
}
]
}
</code>

=== Sample software.json ===
<code type="javascript">
{
"software": [
{
"id": "myappsandroid",
"folder": "myappsandroid",
"binary": "myapps.apk",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "myApps Android",
"description": "myApps for Android"
},
{
"id": "myappswindows",
"folder": "myappswindows",
"binary": "myAppsSetup.msi",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "myApps Windows",
"description": "myApps for Windows"
}
]
}
</code>

=== Sample phoneplatform.json ===
<code type="javascript">
{
"phoneplatforms": [
{
"id": "arm64",
"text": "Phone Platform",
"file": "phone-platform.img",
"folder": "yocto2",
"version": "2063"
}
],
"devices": [
{
"id": "IP270",
"phoneplatforms": [
"arm64"
]
}
]
}
</code>

=== API to download rental history ===

You can download the history as a UTF-8 CSV file with simple '''HTTP GET''' requests with '''digest''' authentication. 
The CSV file uses the semicolon as delimiter. 
 
The URL to download the history is e.g.: 
'''<code>https://mydomain.com/mydomain.com/devices/csvapi?...</code>'''

You can find this path by editing the instance in the AP manager.
In the listed paths, you'll find something which ends with csvapi

In the innovaphone Cloud environment, the URL can be retrieved by taking a look at the Devices App object inside the cloud PBX and replacing the ending '''innovaphone-devices''' with '''csvapi''' inside the App URL, so it looks e.g. like this:

https://cloud-apps0.innovaphone.com/cloud.innovaphone.com/devices/csvapi

====CSV columns====
Most columns should be self explaining, but the column '''invoice reference''' refers to a value which you can configure manually in the domain settings in the Devices App!

====Digest authentication====
You can login with two different username/password combinations, while the domain is the digest username:

* If you use the domain and password of your Devices App instance inside the AP Manager, you have automatically access to all domains. 
* If you use the domain name of any domain as digest username and the configured domain password, you'll have access to this domain and all domains to which this domain has access to

====Query parameters====
The following query parameters can be used (don't forget to URL encode the parameter values, if neccessary!):
* all: if '''1''' or '''true''', the history is queried for all domains where the digest user has access to
* domain: required, if ''all'' is not set
* lang: the output language of the CSV file, which also controls date and number formats, e.g. '''en''', '''de''', ...
* tz: the timezone for dates, e.g. '''Europe/Berlin'''
* type: two types are available:
** '''history''': history which contains changes
** '''overview''': a monthly overview with the iSC costs at the first of the last months
* from: unix timestamp (UTC) in milliseconds, ignored for type=overview
* to: unix timestamp (UTC) in milliseconds, ignored for type=overview

====Example requests====
* <code>https://mydomain.com/mydomain.com/devices/csvapi?domain=mydomain.com&type=overview&lang=en&tz=Europe%2FBerlin</code>
* <code>https://mydomain.com/mydomain.com/devices/csvapi?domain=mydomain.com&type=history&lang=en&tz=Europe%2FBerlin&from=1601903431000&to=1601903385000</code>
* <code>https://mydomain.com/mydomain.com/devices/csvapi?all=1&type=overview&lang=en&tz=Europe%2FBerlin</code>

=== Supported DECT handsets ===

The following handsets are supported for update jobs and the DECT handsets configuration:

* IP64
* IP65
* D81
* D83

== Known issues ==

===SoftwarePhone===
The Devices App is not meant to be used with the windows SoftwarPhone standalone installation.

== Related Articles ==
* [[Howto:Software_Rental]]

Howto16r1:Firmware Upgrade V15r1 V16r1

2026-04-10T09:11:34Z

Dde: /* Projects */

== Applies To ==
This information applies to:

* All 16r1 capable innovaphone devices
: For a general overview of the upgrade process and a list of supported devices with 16r1, see [[Howto:Firmware Upgrade]]
== Licenses ==
In case of cloud or rental model, don't worry about licenses.

If the system is licensed on premise, you'll need to regenerate the license file for v16 in https://portal.innovaphone.com/ and load into the system before upgrade (The system needs to have the SSC up to date).

== Migration Policy ==
Before you begin, be sure that your whole installation is running the latest 15r1 service release. Create backups before you start and store them on an external location 

=== TechAssist Upgrade Helper ===
* Before you start, make sure that all TechAssist tests (you will receive the required tests in the last update in the previous major version) labelled <code>Pre Upgrade: xy</code> are positive, if available
* When you are finished, make sure that all TechAssist tests (you will receive new tests with the upgrade) are positive

=== New TLS Profile ===
Please note that we have changed our TLS profiles ([[Reference16r1:IP4/General/TLS]]). The new ''Normal'' setting, which is the default value, now only allows TLS 1.3 and TLS 1.2.

== Changes visible to the end customers ==
Listed here are changes that should be communicated by resellers to end users prior to a upgrade, as the change will be visible/audible in the behaviour of the application/device.

* ''Nothing''

== Manual steps needed after upgrade ==
If the installer is not used for a new installation, some new default settings are not set. Please evaluate per app whether you want to configure the new default settings manually.

=== Connector for Microsoft 365 ===
If you plan to use the new '''Contact Search''' feature of the Connector for Microsoft 365, you need to perform two manual Steps:
# Create the '''microsoft365-api''' app object by using the Settings template
# Assign the '''microsoft365-api''' app object to every user who should be able to use the new Contact Search feature. (Of cause, you can use a template for that)
 
For a more detailed guide, please refer to the how-to article: [[Howto16r1:Configure Contact Search by Connector for Microsoft365#Creating the PBX app object using the PBX Manager Plugin]]

=== Remote Control ===
In order to use the Admin Configuration Panel of the Settings App – AP Remote Control, it is necessary to grant access to the '''admin''' API, available in the App tab of the Remote Control App object.

=== Working ===
For badge counts to work, the Working Manager app object must have '''Websocket''' and '''PbxSignal''' enabled.
For the Connect integration of the Working app, '''Websocket''', '''Services''' and '''connect'''(in the Apps tab) must be enabled in the Working User app.

=== Switchboard ===
For the Connect Integration (Call Notes) to work, the Switchboard App must have the '''Services''' (App-tab) and '''connect''' or '''messages''' (Apps-tab) enabled (the name depends when the PBX was installed).

=== Projects ===
* Projects requires '''App platform version 140029''' or higher, so updating the App Platform before Projects is recommended. The Store will prohibit the update if the App Plattform does not have the minimum required version.
* For some extra admin-functionalities the '''Projects App Object needs to have an admin mode''' (App-tab). Easiest way to set this new mode is to the open the Projects App via the Projects Plugin Settings App and to re-apply it (click the OK-button). The same plugin can also be used to distribute this mode via the Config Templates.
* The '''App Platform requires the correct Time and a Timezone''' set under AP Manager/Settings/General. This is needed for some automatic cleanup of deleted items and automatic task status updates (done around 00:00h on the due date).

== New Apps ==
New Apps will not be installed automatically by the upgrade. The installation description of new apps is usually in the concept article. Please rate per app whether you want to install/use the new app and configure it manually.

* App Polls: [[Reference16r1:Concept App Polls]]
* App Service Conference Transcriptions [[Reference16r1:Concept_App_Service_myApps_Assistant]]
* App Service Connector for Whatsapp: [[Reference16r1:Concept_App_Service_Connector_for_Whatsapp]]
* App Conference Scaler: [[Reference16r1:Concept_Conference_Scaler_App]]
* App Service IP: [[Reference16r1:Concept App Service IP]]

== Removed ==
The following software is no longer included.

* IP110A (can still be used with 15r1 firmware on current PBX versions)
* IP240A (can still be used with 15r1 firmware on current PBX versions)
* CA on CF card feature

== Deprecated ==
The following software is based on legacy technology, with no further development and limited maintenance and support.

* ''Nothing''

== Previously deprecated and now no longer supported ==
The following software is based on legacy technology, with no further development and no more maintenance and support.

* ''Nothing''

==Known Problems==
===Long Update-duration===
When you update, it can be up to 10 minutes before you have access to your app platform again.

== Related Articles ==
*[[Howto:Firmware_Upgrade]]
* [[Howto15r1:Firmware_Upgrade_V14r2_V15r1]]
[[Category:Howto|{{PAGENAME}}]]

Howto16r1:Firmware Upgrade V15r1 V16r1

2026-04-10T09:01:53Z

Dde: /* Project */

== Applies To ==
This information applies to:

* All 16r1 capable innovaphone devices
: For a general overview of the upgrade process and a list of supported devices with 16r1, see [[Howto:Firmware Upgrade]]
== Licenses ==
In case of cloud or rental model, don't worry about licenses.

If the system is licensed on premise, you'll need to regenerate the license file for v16 in https://portal.innovaphone.com/ and load into the system before upgrade (The system needs to have the SSC up to date).

== Migration Policy ==
Before you begin, be sure that your whole installation is running the latest 15r1 service release. Create backups before you start and store them on an external location 

=== TechAssist Upgrade Helper ===
* Before you start, make sure that all TechAssist tests (you will receive the required tests in the last update in the previous major version) labelled <code>Pre Upgrade: xy</code> are positive, if available
* When you are finished, make sure that all TechAssist tests (you will receive new tests with the upgrade) are positive

=== New TLS Profile ===
Please note that we have changed our TLS profiles ([[Reference16r1:IP4/General/TLS]]). The new ''Normal'' setting, which is the default value, now only allows TLS 1.3 and TLS 1.2.

== Changes visible to the end customers ==
Listed here are changes that should be communicated by resellers to end users prior to a upgrade, as the change will be visible/audible in the behaviour of the application/device.

* ''Nothing''

== Manual steps needed after upgrade ==
If the installer is not used for a new installation, some new default settings are not set. Please evaluate per app whether you want to configure the new default settings manually.

=== Connector for Microsoft 365 ===
If you plan to use the new '''Contact Search''' feature of the Connector for Microsoft 365, you need to perform two manual Steps:
# Create the '''microsoft365-api''' app object by using the Settings template
# Assign the '''microsoft365-api''' app object to every user who should be able to use the new Contact Search feature. (Of cause, you can use a template for that)
 
For a more detailed guide, please refer to the how-to article: [[Howto16r1:Configure Contact Search by Connector for Microsoft365#Creating the PBX app object using the PBX Manager Plugin]]

=== Remote Control ===
In order to use the Admin Configuration Panel of the Settings App – AP Remote Control, it is necessary to grant access to the '''admin''' API, available in the App tab of the Remote Control App object.

=== Working ===
For badge counts to work, the Working Manager app object must have '''Websocket''' and '''PbxSignal''' enabled.
For the Connect integration of the Working app, '''Websocket''', '''Services''' and '''connect'''(in the Apps tab) must be enabled in the Working User app.

=== Switchboard ===
For the Connect Integration (Call Notes) to work, the Switchboard App must have the '''Services''' (App-tab) and '''connect''' or '''messages''' (Apps-tab) enabled (the name depends when the PBX was installed).

=== Projects ===
* Projects requires '''App platform version 140003''' or higher, so updating the App Platform before Projects is recommended. The Store will prohibit the update if the App Plattform does not have the minimum required version.
* For some extra admin-functionalities the '''Projects App Object needs to have an admin mode''' (App-tab). Easiest way to set this new mode is to the open the Projects App via the Projects Plugin Settings App and to re-apply it (click the OK-button). The same plugin can also be used to distribute this mode via the Config Templates.
* The '''App Platform requires the correct Time and a Timezone''' set under AP Manager/Settings/General. This is needed for some automatic cleanup of deleted items and automatic task status updates (done around 00:00h on the due date).

== New Apps ==
New Apps will not be installed automatically by the upgrade. The installation description of new apps is usually in the concept article. Please rate per app whether you want to install/use the new app and configure it manually.

* App Polls: [[Reference16r1:Concept App Polls]]
* App Service Conference Transcriptions [[Reference16r1:Concept_App_Service_myApps_Assistant]]
* App Service Connector for Whatsapp: [[Reference16r1:Concept_App_Service_Connector_for_Whatsapp]]
* App Conference Scaler: [[Reference16r1:Concept_Conference_Scaler_App]]
* App Service IP: [[Reference16r1:Concept App Service IP]]

== Removed ==
The following software is no longer included.

* IP110A (can still be used with 15r1 firmware on current PBX versions)
* IP240A (can still be used with 15r1 firmware on current PBX versions)
* CA on CF card feature

== Deprecated ==
The following software is based on legacy technology, with no further development and limited maintenance and support.

* ''Nothing''

== Previously deprecated and now no longer supported ==
The following software is based on legacy technology, with no further development and no more maintenance and support.

* ''Nothing''

==Known Problems==
===Long Update-duration===
When you update, it can be up to 10 minutes before you have access to your app platform again.

== Related Articles ==
*[[Howto:Firmware_Upgrade]]
* [[Howto15r1:Firmware_Upgrade_V14r2_V15r1]]
[[Category:Howto|{{PAGENAME}}]]

Reference16r1:Concept App Service Devices

2026-04-09T09:29:29Z

Dde: Created page with "Apps The App Service Devices is an App Service which can be installed on an innovaphone App Platform. It is used to administrate the innovaphone devices which belong to the whole installation. == Applies To == * innovaphone PBX from version 13r1 == Apps == === Devices App (innovaphone-devices) === This is the standard UI App for Devices. Parameters: ;Websocket: to publish the com.innovaphone.devicesui-API, which can be used to link directly to..."

[[Category:Concept|Apps]]
The App Service Devices is an App Service which can be installed on an innovaphone App Platform. It is used to administrate the innovaphone devices which belong to the whole installation.
== Applies To ==

* innovaphone PBX from version 13r1

== Apps ==

=== Devices App (innovaphone-devices) ===
This is the standard UI App for Devices.

Parameters:

;Websocket: to publish the com.innovaphone.devicesui-API, which can be used to link directly to devices (which is done e.g. inside the Events app)

=== Devices API (innovaphone-devices-api) ===
This is a hidden App, which provides the Devices API (com.innovaphone.devices). This API can be used to find and communicate with devices which are registered to the Devices App.

Additionally it acts as a provider of the Search API (com.innovaphone.search). So you can find devices and domains in other apps like the Search App.

Parameters:

;Hidden: DevicesApi must be a hidden App
;Websocket: to get the URL of the Devices App itself which is used for provisioning

== PBX Manager Plugins ==

=== Devices ===

With the Devices plugin App objects can be created, edited and deleted for Devices and the Devices API on the PBX.

== Concepts ==
All innovaphone hard phones and gateways starting from version 13r1 can establish a registration inside the Devices App and therefor administrative tasks can be performed through the App.

=== Domains ===

In a hosted environment, it might be needed to add multiple domains to the Devices App. 
After the initial installation of Devices through Install, you have administrative rights and can add more domains.

==== Administrative rights ====
You have administrative rights if the configured PBX App object for Devices uses the password of the instance which is configured in the Manager App and the PBX uses the same domain as this instance.

==== Domain local rights ====
You have just rights to a certain domain if the configured PBX App object for Devices uses the domain password which can be configured in Devices for each domain and the PBX uses the same domain name as configured in Devices.

==== Assign rights to other domains ====
Domains can gain access to other domains by configuring these access rights in the Devices App.

==== Deploy passwords and access rights ====
During install, a domain is created inside the Devices App. There is a checkmark Deploy the domain password on all devices which is set by default and which is the same as the administrative password.
If you change the domain password, all passwords on all administrative devices and app platforms which are connected to this domain will be also changed. 
Since 13r2sr25/13r3sr7/14rx: devices which are auto provisioned or provisioned through the Profile/Users Admin App will get a random password instead of the domain password.
If you add a phone device manually to a domain inside the Devices App, this phone device will also get a random password. Other device types added manually or devices added with a provisioning code which has been created within the Devices App directly, will get the domain password instead as long as you do not tick the checkmark '''Provision device with a random password'''. 
 
This will also set the manager password and the SSH passwords of App Platforms. 
 
The clear text random passwords can be requested and viewed in the settings of a device in the Devices App.

Attention: If you untick the '''Deploy administrative devices passwords''' checkmark, the password won't be deployed anymore, but also not reconfigured to the default password!

Attention: After each reconnect of a client, the password will be deployed again.
This means, if the checkmark is set and you set another password somewhere else (e.g. under General::Admin),
this password will be just valid until the next reboot or reconnect to the Devices App!

;Create new random passwords
You can rollout new random passwords by unticking the '''Deploy administrative devices passwords''' checkmark and ticking it again. 

;Changing a device from random to domain password
Starting with 16r1, you can edit a device and un-/tick "Use random password" to change the password method for each device separately.

;Devices with multiple domains (Cloud)
In a hosted environment, you can use the Devices App with multiple domains. The corresponding instance of Devices has a configured domain and an instance password set inside the manager. 

The hosting PBX has a domain inside Devices with a specific password. 
If this domain name matches the instance domain of the Devices instance and the password matches either the instance password or the domain password, you will be logged in as admin and have access to all domains. 

Each newly created domain has its own password inside Devices. If you create an App Object inside a PBX with this domain and the password of this domain (inside Devices), you will just have access to this single domain. 

Devices also has the possibility to grant access to other domains for a specific domain.

=== Categories ===

There are two types of categories:
* provisioning category: used for device configurations and provisioning
* standard category: used for update/backup jobs and device management

Each device can have just a '''single''' provisioning category, as it receives it's configuration by all configured device configurations for this provisioning category.

In addition, a provisioning category, which is used inside an analogue phone/phone device configuration '''cannot''' be used to provision a gateway.

=== Device connections ===
The Devices registration is done through a websocket connection to the webserver of the App Platform and the Devices instance (standard HTTP/s port). 
The URL used can be configured manually under [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:General/Devices_Registration Devices Registration] or through a new provisioning mechanism. 
 
A binary protocol is used to transfer information between the device and the devices App. The MAC address is the unique key to identify a device. 
 
If a device is added to a domain in Devices, the device gets a unique random password. Without such a password, a device shows up as '''unassigned''' in the Devices app.
This is also the case after a long reset or when the device lost its configuration. 
 
In such a case, the device has to be manually added again to a domain or it has to be provisioned again.

If a device is not assigned to a domain or provisioning category, it won't receive any configurations.

==== Devices Registrations ====
See [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:General/Devices_Registration Devices Registration]

==== Second Devices Registration URL ====

The firmware has a second SYSCLIENT2 module, which can be configured to point to a different Devices instance and the AP Manager also has a second Devices Registration URL. 
 
If you use this configuration option, you should take care and consider:

* if the Devices domain from the second configuration provides a password for all devices, the password is ignored, as it would lead to inconsistend passwords otherwise (from 13r1 SR12 on)
* the Devices domain from the second configuration should not provide Devices Configurations or Update Jobs as these might collide with configurations from the first Devices instance!

Generally, only one of the two ''Devices'' App instances connected to the device must apply changes to the device.

We strongly discourage the usage of this second configuration option due to unexpected behaviour if incorrectly used!
Never use the second URL if you use software or hardware rental!

==== Device information ====

The following data is transferred:
* MAC address
* device type (e.g. IPVA, AppPlatform, IP112)
* IP addresses (IPv4, IPv6)
* version (not searchable)

You can also search for this data inside the devices tab in the App.


=== Provisioning ===
Devices can be added by provisioning (both phones and gateways).
The standard online provisioning looks like this:
* a user or administrator creates a provisioning code in the Devices or Users App (this stores the Devices URL on the provisioning server side)
* a device with 13r1 or newer is connected to the network after a long reset
* the provisioning code has to be entered within one hour (after one hour, the Update URL isn't polled anymore)
* the device sends this code to config.innovaphone.com and retrieves the Devices URL
* the device connects to the Devices URL and is added to the domain where the code has been created

There is also an [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Offline_Provisioning offline provisioning mode]. 
There is also an [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Provisioning#Automatic_provisioning automatic provisioning mode].

Note: provisioning is cancelled if the device already belongs to another domain in the same Devices instance! This prevents the unauthorized move of a device between different domains.

==== Devices Registration URL ====

The Devices Registration URL which is set through the provisioning process, always starts with '''wss'''. This is not dependent anymore on the App URL which is configured inside the PBX Devices App object.

=== Updates ===
The Devices App can be used to rollout updates. 

==== JSON files ====
The update files have to be acccessible on a webserver without authentication and four json files are used:
* firmware.json: innovaphone device firmware
* apps.json: Apps for the App Platform
* software.json: contains software for DECT handsets
** just IP64 and IP65 are used and supported
* phoneplatform.json: contains the phone platform image for e.g. the IP270

You can either use the standard innovaphone App Store for these files or your own local webserver. 

==== Update jobs ====
You can configure several update jobs with different categories to organize your updates. 
Update jobs are always sequentially processed and inside one update job, just '''20''' devices are updated at the same time.

==== Device update check after the update job has been already executed====
If a device goes online, the newest suitable update job is searched for this device (depending on the categories). 
If an update job is found, the update is just performed, if there has been '''no''' successfull update for this device in this job before and the version does not match (simply string compare).

====Update errors====
If an update fails, the Devices App shows an error. You may have to enable further tracing on the updated device itself to find out the reason of the failure. 
 
* on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0 module and take a look at the events which may already tell you the reason
* on an App Platform, enable the App and HTTP Client trace flag on the manager

An update job is retried '''two''' times if updates inside this job failed. The retry is done '''ten''' minutes after the update job finished previously.

====innovaphone myApps====
The path to the App Store and the used innovaphone myApps version is updated to the version of the gateway on gateways with an enabled PBX after a successfull update. 
This configuration can be found [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:PBX/Config/myApps here]

Inside the configuration on an update job, the flag "Do not update myApps launcher software" disables the update of the innovaphone myApps version inside PBXes.

====DECT handsets====
If you check the update DECT handsets checkmark, all DECT devices will be configured to rollout updates to DECT handsets. 
See [[{{NAMESPACE}}:Concept_App_Service_Devices#Supported_DECT_handsets | Supported DECT handsets]].

The DECT handset firmware will be searched inside the configured software.json.

=== Backups ===
The Devices App can be used to backup the configuration and data of Apps and devices. 

====Webserver requirements====
Backups are stored on a webserver with or without Digest/Basic authentication and with the '''webdav PUT''' method.

====Backup jobs====
Backup jobs are executed sequentially. Inside one backup job, just '''20''' backups are performed at the same time.

====Phones or gateways====
The configuration file is stored. Therefor the Devices App tells the device to store the configuration with a !mod cmd UP0 /sync prot URL.

====Apps on an App Platform====
The databases of all existing instances and the manager are stored. 
Each installed App Service can have multiple instances and each App instance has its own database. 
A database contains '''both''' configuration and data of an App instance! 
The manager database contains the webserver certificate and further manager related configuration settings.

The Devices App establishes a websocket connection to the manager and tells the manager where to store the backups. 
The manager on the backuped App Platform itself performs the HTTP requests to store the files.

====Backup errors====
If a backup fails, the Devices App shows an error. You may have to enable further tracing on the backuped device itself to find out the reason of the failure.

* on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0
* on an App Platform, enable the App and HTTP Client trace flag on the manager

=== Restore ===
====Phones or gateways====
Just as always under [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Administration/Upload/Config Upload Config].

====Apps====
The App Service itself has to be installed on the App Platform prior restoring of a single instance. 
The restoring is done in the Manager App on the App Platform itself. 
The instance settings, the configuration and data are restored in a single process.

=== Device Configurations ===

You can define several device configurations. These configurations are either applied to all devices inside this domain or to selected categories. 
Configurations are applied on creation and on every reconnect of a matching device.

==== Transfer checkmarks ====

Some configuration options have a specific checkmark to enable the transfer of the option. 
 
* Checkmark disabled:
** configuration option field(s) are disabled
** option values are '''not''' transferred at all
* Checkmark enabled:
** configuration option field(s) are enabled
** option values are transferred, even if field values are empty

==== Expert configuration ====

The expert configuration can be used to configure different settings which are not available inside the other device configurations. 
You can use the standard syntax of an update server script (see [[ {{NAMESPACE}}:Concept_Update_Server | Concept Update Server ]] for a general overview and the section on [[Howto:PHP_based_Update_Server_V2#Hints_for_writing_your_update_snippets | Hints for writing your update snippets ]] (note that the remainder of this article relates to the now deprecated old mechanism, so please disregard the rest)). 
 
Some hints:
* the expert configuration is just executed once after a device restarted and on change of the expert configuration itself
* the expert configuration is executed after all other device configuration types, so that you can override changes
* to make configuration changes effective, you may also need to issue a final ''config write'', ''config activate'' and ''iresetn'' command (see the [[ {{NAMESPACE}}:Concept_Update_Server#Check_command | ''check'' command]] for details)
* some commands shouldn't be used inside the script:
** [[ {{NAMESPACE}}:Concept_Update_Server#Times_command |''times'']]: since the expert configuration is executed only once after a reboot of the device and when changes are made, it does not make sense to use the ''times'' command
** [[ {{NAMESPACE}}:Concept_Update_Server#Prot_command |''prot'']]|[[ {{NAMESPACE}}:Concept_Update_Server#Boot_command |''boot'']]: use an update job instead
** [[ {{NAMESPACE}}:Concept_Update_Server#Scfg_command |''scfg'']]: use a backup job instead
** [[Howto:PHP_based_Update_Server_V2#Using_vars_create|''vars create'']]: this cmd will always raise the ''reset needed condition'' and the aforementioned ''iresetn'' command would always execute therefore. As a result, the devices would enter a boot loop. Be sure to avoid this using an appropriate [[ {{NAMESPACE}}:Concept_Update_Server#Check_command |''check'' command ]] and update its ''<serial>'' properly whenever the expert configuration is changed

==== Certificates configuration ====
You can use this configuration to rollout certificates to the trust list of your devices. 

* Manual upload certificates.
* Configure up to five URLs which are polled every 24 hours. They must return files with PEM formatted public keys (one or more) which are then rolled out.
** certificates are just rolled out if differences are determined, so if URLs are polled and no changes are detected, certificates are not rolled out again. Changes are detected by fingerprint comparison of each embedded certificate
** if a device restarts, the configuration is applied again. Just the fingerprints of the device trust list are checked against the configuration trust list and just on differences, certificates are rolled out again
* Configure https://download.innovaphone.com/certificates/innovaphone.pem to always have the innovaphone public keys in your trust list (e.g. used for our push service).
* Configure https://download.innovaphone.com/certificates/ca.pem to always have the innovaphone Device Certification Authority certificates in your trust list.
* Configure https://download.innovaphone.com/certificates/ca-unverified.pem to always have the innovaphone Unverified Device Certification Authority certificates in your trust list.
** The Unverified CA is used for non hardware devices, e.g. IPVAs, which are not shipped with an official innovaphone Device Certification Authority certificate, as innovaphone has no control over the serial number here.
* Configure https://curl.se/ca/cacert.pem to always have the public Root Certifications Authorities in your trust list.

Using this configuration, the trust list can only be managed through ''Devices'' because it is cleared before each rollout.

==== DECT Handsets ====

This configuration can be used to configure specific options like language, voicemail number etc. for DECT handsets. 
 
* all DECT devices like IP1202, IP1203 etc. will receive this configuration (of course just if the configured categories match)
* Devices configures a URL like https://domain.com/domain.com/devices/parameters/id.xml on the specific DEVMANBW module.
* This file is then polled by the basestations and the read values are transfered to the DECT handsets.
* see [[{{NAMESPACE}}:IP1202/IP1203_DECT_System#Configuration_of_Handset_parameters]]

See [[{{NAMESPACE}}:Concept_App_Service_Devices#Supported_DECT_handsets | Supported DECT handsets]].

=== Software rental ===
Regarding the Software Rental program and the Payment Method, please refer to:
* [[{{NAMESPACE}}:Concept_Software_Rental|Concept Software Rental]]

Software rental can be done for innovaphone Cloud installations or for software, which operates on the customer premisis. This could eventually be customer owned hardware or a privat virtual machine, managed by the customer.

==== Hardware licenses ====
Hardware licenses have to be bound on the specific device in my.innovaphone itself and currently can't be handled within the Devices App itself. So you also need to download the licenses from my.innovaphone and upload them on the device with the already known methods.

===== Hardware licenses with software rental =====
If your device has software rental licenses, you can bind hardware licenses within my.innovaphone in the software rental project itself.

===== Hardware licenses without software rental =====
If your device does not have software rental licenses, you should bind hardware licenses in a separate non rental project in my.innovaphone.

==== innovaphone Cloud ====
Inside the innovaphone Cloud, you just have to upload your activation keys with iSCs to add licenses to one or more gateways. 

==== Email expiry notifications ====
You will receive an email notification if the rental of a project expires. This notification will be sent '''seven''' weeks before the expiry and then once a week until the rental expires. 
You can configure one or more email recipients in the domain settings. 
If no email address is configured, the email address of the logged in user account is used.

==== History ====
You can download the history in the Devices App. You'll get a CSV file (semicolon separated). The date and number format depends on the selected language in the UI. 
There is also an API available for automated downloas, which is described [[ {{NAMESPACE}}:Concept_App_Service_Devices#API_to_download_rental_history|here ]].

====Own installation====
Inside your own installation, you have to register a new my.innovaphone account or you can use an existing account inside the Devices App. 
One domain inside Devices belongs to one project inside your my.innovaphone company, so you can handle multiple domains with one my.innovaphone account.

====Technical aspects====
A new rental expiration date is calculated on each license or balance change in the domain. 
So after each change new licenses with a new date are transfered to the gateways and also stored in the Devices App itself. 
If the rental expires, the gateway reboots and the licenses are not available anymore. 
The licenses are also transfered after each reconnect of a gateway to the Devices App. 
 
For license and balance changes, the Devices App must be online and have access to my.innovaphone.com!

====Usage====
You have to add (use the + symbol) a PBX and select all licenses you want to rent. 
Use the '''apply''' button to really bind these licenses. Without usage of the apply button, you can just see a precalculation of the iSCs/month and the rental end date, but nothing is really charged from your balance.

===Change of IP address/DNS name in PBX object===
If the IP address or DNS name inside the PBX object of the Devices App changes, all currently connected clients get a new Devices Registration URL and also all clients, which connect afterwards with the old host name.

== Appendix ==
=== Sample firmware.json ===
<code type="javascript">
{
"devices": [
{ "id": "IP0010", "versions": [ "13r1" ] },
{ "id": "IP0011", "versions": [ "13r1" ] },
{ "id": "IP101", "versions": [ "13r1" ] },
{ "id": "IP102", "versions": [ "13r1" ] },
{ "id": "IP1060", "versions": [ "13r1" ] },
{ "id": "IP110", "versions": [ "13r1" ] },
{ "id": "IP110A", "versions": [ "13r1" ] },
{ "id": "IP111", "versions": [ "13r1" ] },
{ "id": "IP112", "versions": [ "13r1" ] },
{ "id": "IP1130", "versions": [ "13r1" ] },
{ "id": "IP1260", "versions": [ "13r1" ] },
{ "id": "IP150", "versions": [ "13r1" ] },
{ "id": "IP2000", "versions": [ "13r1" ] },
{ "id": "IP200A", "versions": [ "13r1" ] },
{ "id": "IP22", "versions": [ "13r1" ] },
{ "id": "IP222", "versions": [ "13r1" ] },
{ "id": "IP230", "versions": [ "13r1" ] },
{ "id": "IP232", "versions": [ "13r1" ] },
{ "id": "IP24", "versions": [ "13r1" ] },
{ "id": "IP240", "versions": [ "13r1" ] },
{ "id": "IP241", "versions": [ "13r1" ] },
{ "id": "IP29", "versions": [ "13r1" ] },
{ "id": "IP3010", "versions": [ "13r1" ] },
{ "id": "IP3011", "versions": [ "13r1" ] },
{ "id": "IP302", "versions": [ "13r1" ] },
{ "id": "IP305", "versions": [ "13r1" ] },
{ "id": "IP311", "versions": [ "13r1" ] },
{ "id": "IP411", "versions": [ "13r1" ] },
{ "id": "IP6000", "versions": [ "13r1" ] },
{ "id": "IP6010", "versions": [ "13r1" ] },
{ "id": "IP800", "versions": [ "13r1" ] },
{ "id": "IP810", "versions": [ "13r1" ] },
{ "id": "IP811", "versions": [ "13r1" ] },
{ "id": "IPVA", "versions": [ "13r1" ] }
],
"versions": [
{ "id": "13r1", "build": "131705", "text": "13r1 dvl [131705]", "wiki": "" }
]
}
</code>

=== Sample apps.json ===
<code type="javascript">
{
"apps": [
{
"id": "apidemo",
"folder": "apidemo",
"binary": "apidemo",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "Apidemo",
"description": "The Apidemo"
},
{
"id": "appstore",
"folder": "appstore",
"binary": "appstore",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "AppStore",
"description": "AppStore"
}
]
}
</code>

=== Sample software.json ===
<code type="javascript">
{
"software": [
{
"id": "myappsandroid",
"folder": "myappsandroid",
"binary": "myapps.apk",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "myApps Android",
"description": "myApps for Android"
},
{
"id": "myappswindows",
"folder": "myappswindows",
"binary": "myAppsSetup.msi",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "myApps Windows",
"description": "myApps for Windows"
}
]
}
</code>

=== Sample phoneplatform.json ===
<code type="javascript">
{
"phoneplatforms": [
{
"id": "arm64",
"text": "Phone Platform",
"file": "phone-platform.img",
"folder": "yocto2",
"version": "2063"
}
],
"devices": [
{
"id": "IP270",
"phoneplatforms": [
"arm64"
]
}
]
}
</code>

=== API to download rental history ===

You can download the history as a UTF-8 CSV file with simple '''HTTP GET''' requests with '''digest''' authentication. 
The CSV file uses the semicolon as delimiter. 
 
The URL to download the history is e.g.: 
'''<code>https://mydomain.com/mydomain.com/devices/csvapi?...</code>'''

You can find this path by editing the instance in the AP manager.
In the listed paths, you'll find something which ends with csvapi

In the innovaphone Cloud environment, the URL can be retrieved by taking a look at the Devices App object inside the cloud PBX and replacing the ending '''innovaphone-devices''' with '''csvapi''' inside the App URL, so it looks e.g. like this:

https://cloud-apps0.innovaphone.com/cloud.innovaphone.com/devices/csvapi

====CSV columns====
Most columns should be self explaining, but the column '''invoice reference''' refers to a value which you can configure manually in the domain settings in the Devices App!

====Digest authentication====
You can login with two different username/password combinations, while the domain is the digest username:

* If you use the domain and password of your Devices App instance inside the AP Manager, you have automatically access to all domains. 
* If you use the domain name of any domain as digest username and the configured domain password, you'll have access to this domain and all domains to which this domain has access to

====Query parameters====
The following query parameters can be used (don't forget to URL encode the parameter values, if neccessary!):
* all: if '''1''' or '''true''', the history is queried for all domains where the digest user has access to
* domain: required, if ''all'' is not set
* lang: the output language of the CSV file, which also controls date and number formats, e.g. '''en''', '''de''', ...
* tz: the timezone for dates, e.g. '''Europe/Berlin'''
* type: two types are available:
** '''history''': history which contains changes
** '''overview''': a monthly overview with the iSC costs at the first of the last months
* from: unix timestamp (UTC) in milliseconds, ignored for type=overview
* to: unix timestamp (UTC) in milliseconds, ignored for type=overview

====Example requests====
* <code>https://mydomain.com/mydomain.com/devices/csvapi?domain=mydomain.com&type=overview&lang=en&tz=Europe%2FBerlin</code>
* <code>https://mydomain.com/mydomain.com/devices/csvapi?domain=mydomain.com&type=history&lang=en&tz=Europe%2FBerlin&from=1601903431000&to=1601903385000</code>
* <code>https://mydomain.com/mydomain.com/devices/csvapi?all=1&type=overview&lang=en&tz=Europe%2FBerlin</code>

=== Supported DECT handsets ===

The following handsets are supported for update jobs and the DECT handsets configuration:

* IP64
* IP65
* D81
* D83

== Known issues ==

===SoftwarePhone===
The Devices App is not meant to be used with the windows SoftwarPhone standalone installation.

== Related Articles ==
* [[Howto:Software_Rental]]

Reference16r1:Concept myApps platform services

2026-03-26T08:13:14Z

Dde: /* MSI Parameters and install options */

[[Category:Concept|myApps]]

myApps platform services provide various operating system specific services which can be used by other ''Apps'' running in the [[{{NAMESPACE}}:Concept myApps|myApps client]]. Those services typically are not available in the browser's JavaScript environment and hence must be implemented in native platform code. Therefore, the platform services are installed as native executable on the respective platform.

When myApps is started in a web browser (and hence has no access to the platform services), some Apps will use [https://en.wikipedia.org/wiki/WebRTC WebRTC] services implemented by the browser instead. For ease of reference, features available in this scenario are also described here.

On windows, the platform services also come with their own web browser in which the myApps web App will be started then. This browser is based on google's [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium] open source software.
= Applies To =

* [[{{NAMESPACE}}:Concept myApps|myApps]]
* myApps for Windows
* myApps for macOS
* myApps for iOS
* myApps for Android
* myApps Web App (WebRTC)
* myApps for IP270
version 16r1

=Features=
Not all features are available or required on all platforms.
{|
! style="text-align: left; font-weight: bold" | Feature
! style="text-align: left; font-weight: bold" | Description
! style="text-align: left; font-weight: bold"| Availability
|-
| || || Windows || iOS || Android || macOS || Browser<ref>This refers to the myApps web application running in a browser with no platform services available</ref>
|IP270
|-
| [[#Device handling|Audio Devices]] || manage local audio devices to record and playback audio conversations || ✔ || ✔ || ✔ || ✔ || ✔ (audio available but devices managed by web browser) || ✔
|-
| Video || manage local displays and cameras to capture and render video live stream || ✔ || ✔ || ✔ || ✔ || ✔ (video available but devices managed by web browser) || ✔
|-
| Ringer || manage local ringing device || ✔ || ✔ || ✔ || ✔ || ✔ || ✔
|-
| [[#Application sharing|Application sharing]]
|-
|   presenter || share an application || ✔ || ✗ || ✔ || ✔ || ✔ || ✔
|-
|   consumer || view an application shared by the peer || ✔ || ✔ || ✔ || ✔ || ✔ || ✔
|-
| [[#Hot keys|Hot keys]] || capture key presses for quick invocation of phone apps (e.g. dial selected number) || ✔ || ✗ || ✗ || ✔ || ✗ || ✗
|-
| [[#URL Handler|tel: and sip: URI handler]] || intercept clicks on tel: and sip: links in web sites to invoke phone apps || ✔ || ✔ || ✔ || ✔ || ✗ || ✗
|-
| [[#User activity|User activity]] || set presence state according to user activity || ✔ || ✗ || ✗ || ✔ || ✔<ref>limited, see [[#User activity|User activity]] below</ref> || ✔
|-
| Docking || myApps can be docked persistently to the right or left edge of your screens || ✔ || ✗ || ✗ || ✗ || ✗ || ✗
|-
| Multi-windowing || Apps can be launched in separate windows|| ✔ || ✗ || ✗ || ✔ || ✗ || ✗
|-
| [[#Recording|Recording]] || Calls can be recorded to recording app|| ✔ || ✔ || ✔ || ✔ || ✗ || ✔
|-
| [[#Notifications|Notifications]] || ||
|-
|   display notifications || display notifications with OS standard mechanism || ✔ || ✔ || ✔ || ✔ || ✔ || ✗
|-
|   push notifications || receive push notifications while myApps is not running || ✗ || ✔ || ✔ || ✔ || ✔<ref>The browser needs to be running in order to receive push notifications.</ref> || ✗
|-
|   chat and apps || display notifications for chat and other apps || ✔ || ✔ || ✔ || ✔ || ✔ || ✗
|-
|   calls || display notifications for incoming calls || ✔ || ✔ || ✔ || ✔ || ✗<ref>Call notifications are only displayed locally while the phone or softphone app is started.</ref> || ✗
|-
| [[#Local phonebook access|Local phonebook]] || access local phone book || ✔ || ✔ || ✔ || ✔ || ✗ || ✗
|-
| [[#Microsoft Office Integration|Office presence provider]] || maps PBX presence state to Microsoft office presence state || ✔ || ✗ || ✗ || ✗ || ✗ || ✗
|-
| [[#Call an external application for calls|External application start]] || start arbitrary external applications for calls || ✔ || ✗ || ✗ || ✔ || ✗ || ✗
|-
| [[#App Proxy|App Proxy]]|| a caching proxy that provides app persistence || ✔ || ✔ || ✔ || ✔ || ✗ || ✗
|-
| [[#Auto update|Auto update]] || automatically updates myApps platform services to the same version the PBX has || ✔ || ✔ || ✗ || ✔ || ✔<ref>The then-current web app is always loaded from the PBX upon startup and hence up-to-date by definition</ref> || ✔
|-
| Three party conference || initiate 3-pty-conference using Softphone-App || ✔ || ✔ || ✔ || ✔ || ✗ || ✔
|-
| Exclude VPN || disable use of VPN connections for audio and appsharing || ✔ || ✔ || ✔ || ✔ || ✗ || ✗
|-
| Screen lock || myApps screen lock against unauthorised use || ✗ || ✗ || ✗ || ✗ || ✗ || ✔
|}

<references/>

=Requirements=
* innovaphone PBX 16r1 and up

== Hardware ==
Recommended hardware requirements
* Processor: Dual-core 2Ghz or higher
* RAM: 4 Gb

== myApps for Windows ==
* Windows 11 and up
* Windows Server 2016 and later versions

=== 32 & 64 bit Windows ===
* 32 bit Windows: install the myAppsSetup32.msi from the App Store
* 64 bit Windows: install the myAppsSetup.msi from the App Store
** the 64 bit variant still installs into Program Files (x86), as the main myApps.exe is still a 32bit application
** the 64 bit variant just contains an additional 64 bit binary for the outlook search

=== Windows N editions ===

Windows N editions are missing the ''Media Feature Pack'' which is pre installed on other Windows versions.

Please install the pack from [https://www.microsoft.com/en-us/software-download/mediafeaturepack Microsoft (Windows 10 pack)] before you install myApps. The installer will check if the file <code>C:\Windows\SysWOW64\mfplat.dll</code> exist on your system.

Make sure to install the correct pack depending on your Windows version! There are different packs for Windows 10 1703, 1803, 1809 and 32bit or 64bit etc.

NB: Sometimes the myApps installation will not work even though the media pack is already installed. This is because the installer has no read access to check if the package is already installed. If the above-mentioned file exists and the installer asks to install the Windows Media Feature Pack nevertheless, you have to start the myApps install with administrative rights.

=== Terminal Server environments ===

Audio driver was removed if myApps discovers that it is running in a terminal server environment like Citrix.

The audio driver is needed for the Softphone App but the Softphone App should not use an audio driver at the server side because the audio devices are plugged locally and there would be a delay sending and receiving audio data with the server.

If a customer wants to use the Softphone App at the server side he needs to make use of the myApps Plugin for virtual desktops solution:

[[{{NAMESPACE}}:MyApps_Plugin_for_Virtual_Desktops|Reference15r1:MyApps_Plugin_for_Virtual_Desktops]]

== myApps for macOS ==
* macOS 13 or higher

== myApps for iOS ==
* iOS 16 or higher

== myApps for Android ==
* Android 13 or higher.

== myApps for IP270 ==
Exclusively used in IP270.

= Licenses =
* No license needed for myApps platform services

= Overview =
myApps platform services is a native executable that is installed using the standard mechanisms on the respective operating system. It provides various advanced services which can be used by the myApps web client code as well as the Apps running in the myApps context.

Also, on Windows, the platform services come with their own, dedicated browser to run myApps in. This browser is based on [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium]. On iOS, macOS and Android, it is based upon native embedded web view facilities (such as WKWebView) instead.
== Components ==

=== RTP service for audio and appsharing ===
The RTP service provides audio and appsharing as a video stream. VoIP RTP endpoints (e.g. for softphones). It supports STUN, TURN, ICE, SRTP, DTLS. Note however that unlike WebRTC, these endpoints do not ''require'' ICE and DTLS. In other words, they can communicate also with non-compliant (i.e. older) VoIP devices.

Note that the available capabilities when not running the myApps platform services depend on the used browser's WebRTC implementation. See your browser documentation for details.

Apps can request RTP channels using the [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol]'s ''AllocChannel'' message.

==== RTP ports ====
{|
| audio || 50000 -> 50099
|-
| video (app sharing) || 50100 -> 50199
|}

The RTP service will enumerate all local interfaces and create local HOST candidates for ICE. There is an option however to disregard VPN interfaces (more precisely such interfaces with type of ''IF_TYPE_PPP'' or ''IF_TYPE_TUNNEL''). This can eliminate quality issues when RTP data is transmitted through TCP based VPN tunnels.

SRFLX and RELAY candidates are obtained using the STUN and TURN server configuration passed by the App (e.g the ''softphone'' App) as part of the ''AllocChannel'' request.
<code>{"mt":"AllocChannel","channel":"81429cba-396d-43de-8a76-ec020ba8796e","iceServers":[{"urls":"turn:myturn.domaincom:4077?transport=udp","username":"turnuser","credential":"pwd","credentialType":"password"},{"urls":"stun:mystun.domain.com:4077"}],"dn":"Foo Bar","type":"RemoteRtp","kind":"video"}</code>

==== Codecs ====
The installed myApps launchers provide codecs that can be used by softphone apps for media streams. When running in a web browser the codecs depend on the browser version and operating system. See the documentation of your browser for details.

The following codecs are supported:
{|
!style="text-align:left;width:100px;"|Codec
!style="width:100px"|Windows-Launcher
!style="width:100px"|Android
!style="width:100px"|iOS
!style="width:100px"|macOS
!style="width:100px"|Firefox (Browser)
!style="width:100px"|Chrome (Browser)
!style="width:100px"|Edge (Browser)
!style="width:100px"|Safari (Browser)
!style="width:100px"|Opera (Browser)
!style="width:100px"|IP270
|-
|style="text-align:left; background-color:lightgray" colspan="11"|Audio
|
|-
|G711A
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G711u
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G722
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|[https://caniuse.com/#search=Opus OPUS-NB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|[https://caniuse.com/#search=Opus OPUS-WB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
| colspan="11" style="text-align:left; background-color:lightgray" |Video
|
|-
|[https://caniuse.com/#search=VP8 VP8]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|-
|[https://caniuse.com/#search=VP9 VP9]
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|-
|[https://caniuse.com/#search=H264 H264]
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|style="text-align:left; background-color:lightgray" colspan="11"|Application Sharing
|
|-
|Share
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|Watch
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔*
|}

''* small presentation only'' 
''** only for 1:1 calls, not for conferences

==== Video capture ====
The default resolution for video capture is 1920x1080 if available. Otherwise, 1280x720, 640x480, 352x288 or 320x240 will be used. The frame rate is 30 fps if available, otherwise 15 fps. The resulting average bandwidth could reach 1 Mbps.

==== Application sharing ====
Screen content will be transmitted as video stream by the presenter

==== Device handling ====
The RTP service enumerates microphones, loudspeaker, cameras and ringing devices and notifies apps when devices come and go. It is up to the apps using the devices to store preferences.

The RTP service also enables some extended features (such as hook switch or volume control) for supported USB headsets or Bluetooth headsets connected to myApps.
The supported headset-SDKs determine which headset vendors are recommended to be used with the myApps softphone app. 

For this to work, the following vendor specific development kits are integrated in our myApps client. Be aware that the SDK are updated within our Service release :

{| class="wikitable"
|-
! SDK Vendor !! Supported OS !! SDK Version !! innovaphone Service Release
|-
| Jabra|| MacOS || 1.12.2.0 || 13r3sr9
|-
||| Windows || 1.12.2.0 || 13r3sr10
|-
| Epos ''(formerly Sennheiser)'' || MacOS || 12.4.0.5478 || 14r1sr3
|-
||| Windows || n.a. - [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|to be installed separately]]|| 13r3sr10
|-
| Poly ''(formerly Plantronics)'' || MacOS || 3.25.53799.37131 || 13r3sr9
|-
||| Windows || 3.25.53800.37131 || 13r3sr10
|-
| Yealink || MacOS || 3.1.1.20 || 14r1sr3
|-
||| Windows || 3.1.1.20 || 14r1sr3
|}

Notes:
* It is possible to inhibit the start of the Sennheiser SDK (SenncomSDK.exe) using the <code>DISABLEHEADSETS</code> directive of the installer (see [[#MSI Parameters and install options| MSI parameters]] below).

* Starting with V13r3sr10, the Epos-SDK needs to be installed separately using the Epos Connect software to ensure full compatibility between current Epos headset models and native myApps-Windows client. For details [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|refer to this article]].


myApps-IP270 supports use of [[Reference9:Concept USB Headset|USB devices known for innovpahone desk phones]].

==== Ring tones ====
Ring tones can be played. Apps can choose the tone from a pre-defined list of ring tones.

On Windows, custom ring tones can be uploaded as .mp3 files to the <code>ringtones</code> sub-directory of myApps' roaming directory (which usually is in <code>%appdata%\innovaphone\myApps\ringtones</code>).

On Android, custom ring tones can be added to the system via Android settings.

On iOS, custom ring tones can be uploaded as .mp3 files to the <code>Ringtones</code> subdirectory of the myApps file share that is available in iTunes if the iPhone has been connected via USB.

On macOS, custom ring tones can be uploaded as .mp3 files to <code>~/Library/Containers/com.innovaphone.client-macos/Data/Documents/Ringtones</code>.

==== Debugging ====
For extended debugging, turn on the ''Audio'', ''Media'' and ''AppSharing'' traces in myApps.
=== Hot keys ===
On Windows and macOS systems, myApps platform services can listen for hot keys and invoke certain functions. Invocation is done by sending API messages to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

The hot keys can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below. Any of the function keys F1 to F11 (optionally combined with up to two modifier keys ''alt'', ''ctrl'', ''shift'' or ''win'') can be chosen for each function. If you do not want to start the call with "Hotkey+Enter" because you would have to wait for the focus, the hotkey can also be pressed twice and the number is dialled directly.

; dial selected number : Initiates a call using the currently selected text as target.

: A ''PrepareCall'' message with the ''text'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":"mt":"PrepareCall","text":"13","adjust":true}}</code>

; accept call : Accepts a currently alerting call.

: A ''ConnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"ConnectCall"}}</code>

; reject/disconnect call : Rejects a currently alerting call or disconnects an active call.

: A ''DisconnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"DisconnectCall"}}</code>

=== URL Handler ===

On Windows systems, two URI-handler are installed with the myApps platform services. Windows will call up this URI handler when a user clicks on an appropriate link, for example in a web site.

The handler will the send an API message to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

; tel URI : call a number, e.g. <code>tel:4711</code>

: A ''PrepareCall'' message with the ''num'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","num":"4711","adjust":true}}</code>
; sip URI : call a SIP name, e.g. <code>sip:zkl@innovaphone.com</code>

: A ''PrepareCall'' message with the ''sip'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","sip":"zkl@innovaphone.com","adjust":true}}</code>
; im URI : start chat with SIP name, e.g. <code>im:zkl@innovaphone.com</code>

: A ''StartChat'' message with the ''sip'' argument set to the selected text will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm ''com.innovaphone.chat'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.chat","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartChat","sip":"zkl@innovaphone.com"}}</code>

On macOS systems myApps might be made the default application to handle tel URI e.g. <code>tel:4711</code> via Apple FaceTime. Open the "FaceTime" menu "Settings..." and select myApps as "Default for phone calls".

On iOS ''tel'' URIs are always dialed via GSM. Therefore myApps iOS also reacts to URI schemes ''com.innovaphone.tel'', ''com.innovaphone.sip'' and ''com.innovaphone.im'', e.g. <code><nowiki>com.innovaphone.tel:4711</nowiki></code>, <code><nowiki>com.innovaphone.sip:zkl@innovaphone.com</nowiki></code>, <code><nowiki>com.innovaphone.im:zkl@innovaphone.com</nowiki></code>.

=== User activity ===
On Windows and macOS systems, the myApps platform services can monitor user keyboard/mouse activity and change the user's presence state after a certain amount of inactivity. The timeout can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below.

myApps will then send a [https://sdk.innovaphone.com/doc/appwebsocket/myApps.htm#SetUserActivity''SetUserActivity''] message to the PBX using the ''myApps'' protocol.

: <code>{"mt":"SetUserActivity","inactive":true}</code>

This will change the ''status'' property of the ''im:'' contact for the user's own presence and hence result in a presence update from the PBX to myApps

: <code>{"mt":"UpdateOwnPresence","presence":[{...},{"contact":"im:","activity":"","status":"closed"}]}</code>
The ''closed'' status is reflected in the grey status color when displaying a contact [[Image:myapps-inactive.png|myapps-inactive.png/|myapps-inactive.png/]].

On iOS and Android, the state is set to ''inactive'' as soon as the App is brought to background.
When myApps platform services are not available (i.e. when running the web application in a browser solely) a limited user activity monitoring is available: the state is set to active when the web page is not used for more than 5 minutes.

=== Recording ===

The new launcher offers the possibility to record the audio of incoming and outgoing calls. In order to activate that functionality the URL of the recording instance must be configured in either the PBX (PBX->myApps->Config: Recording URL) or the softphone App (Settings->Audio Recording (URL))

[[Image:PBX-Recording-Settings.png|pbx-recording-settings.png/|pbx-recording-settings.png/]] [[Image:Recording-Softphone-Settings.png|recording-softphone-settings.png/|recording-softphone-settings.png/]].

As long as that URL is configured the audio data of all calls are stored as pcap-files under that URL.
If the URL points to a CF device in the PBX, write access must be granted for that URL (PBX->Services->HTTP->Server:Public compact flash access) and if the URL points to the recording app, the files can be accessed via the recording app [[{{NAMESPACE}}:Concept_App_Service_Recordings|recording]].

Under PBX->myApps the administrator can set a certain default behaviour of the audio recording like whether or not the recording should start automatically at the beginning of the call (Recording by Default ON/OFF), only calls with external numbers should be recorded (Record external calls only) or whether or not the user should be able to start/stop the recording himself (Allow user incall recording control). Except for the last parameter these parameters can also be modified by the user in its softphone settings if the administrator doesn't set the FORCE flag.

If the user was allowed by the admin to control the recording a recording switch is active during the call when the "Media" Panel is opened. There the audio recording may be stopped and continued at will. A red recording notice is shown in the top right corner when the recording actually takes place.

[[Image:Recording-incall-switch.png|recording-incall-switch.png/|recording-incall-switch.png/]]

=== Notifications ===

The myApps platform services can use the OS specific notification mechanism (e.g. ''desktop notifications'' on Windows) to display messages (e.g. ''incoming new chat message'') to the user.

Note that the actual rendering of the notification is under control of the OS. Therefore, myApps must be allowed to show notifications and its appearance can be restricted by OS native settings.

==== Microsoft Windows Notifications ====

Microsoft Windows Server editions (2016, 2019, 2022) are just capable of showing a single ''IncomingCall'' notification at the same time (we couldn't find a workaround for this limitation). 
An ''IncomingCall'' notification is visible the whole time instead of being moved to the action center after a certain time. 
 
A notification about a missed call uses the ''IncomingCall'' type so that this notification is visible until the user returns. 
Due to the above limitation, on a new arriving call such a missed call notification is transformed to a default notification which will be moved to the action center automatically. 
 
On non server editions, you can have multiple IncomingCall notifications at the same time (so two parallel incoming calls will be indeed notified at the same time), but the missed call notification handling is the same on both platforms!

Thus there will be always just '''one''' missed call notification visible and previous missed calls can be found inside your action center!

To see myApps notifications, ensure:
* System -> Notifications
** enable notifications
** disable "Do not disturb" or allow myApps as priority application while "Do not disturb" is active
** enable notifications for myApps in the list of applications
* System -> Focus
** if a focus session is active and the "Do not disturb" is activated during a focus session, make sure that myApps is a priority application (see above)

==== macOS Notifications ====
Notifications are the same as on Windows.
The difference is, that for macOS, notifications need to be allowed in the system settings.
Go to Notifications - myApps, select Banner and enable all check marks.

=== Local phonebook access ===
'''Contact Search:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm ''com.innovaphone.search'' API]]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Search'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{"mt":"Search","type":"contact","search":"john doe"},"apiId":"com.innovaphone.search"}</code>
Search results are delivered as ''SearchInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{"mt":"SearchInfo","relevance":2000,"adjust":true,"type":"contact","contact":{"givenname":"John","sn":"Doe","company":"ACME","position":"Head of everything","telephonenumber":["11111","22222"],"homephone":["+4944444","33333"],"mobile":["+49 (123) 55555"]}},"api":"com.innovaphone.search"}</code>

'''Reverse Lookup:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.phonelookup/lib1_api_phonelookup.htm ''com.innovaphone.phonelookup'' API]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Lookup'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{ mt: "Lookup", prefixIntl: "000", prefixNtl: "00", prefixExt:"0", area: "7031", country: "49", lookup: "0004970311234567" },"apiId":"com.innovaphone.lookup"}</code>

Search results are delivered as ''LookupInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{mt: "LookupInfo", dn: "Jake Blues", contact: { telephonenumber: ["0004970311234567"], givenname: "Jake", sn: "Blues", company: "Blues Brothers" </code>

==== Windows ====
On Windows, the search and lookup are performed in all of the user's Outlook contact folders. As opposed to the search implemented in the ''Contacts'' and ''Users'' App, all items are returned which match any of the search words (i.e. searching for ''a b'' will return items matching either ''a'' or ''b'').

; searched properties : firstname, lastname
; returned properties : Following Outlook contact phone number properties are returned (if available):

:* OFFICE_TELEPHONE_NUMBER as ''telephonenumber''
:* OFFICE2_TELEPHONE_NUMBER as ''telephonenumber''
:* HOME_TELEPHONE_NUMBER as ''homephone''
:* HOME2_TELEPHONE_NUMBER as ''homephone''
:* MOBILE_TELEPHONE_NUMBER as ''mobile''
:* BUSINESS_FAX_NUMBER as ''facsimiletelephonenumber''
Note that contact information is cached in the search provider. Updated contacts may therefore become effective after a while only.
Outlook search will create its own trace file <code>myAppsOutlookSearch-</code>''date-time''<code>.txt</code> in the standard trace directory.

This search provider is always installed and can be disabled. There is no need (nor possibility) to enable it in the ''Apps'' tab of the PBX's user object. Also, no ''App'' object needs to be created for it.

==== Android/iOS ====
The search and lookup are performed in the contacts.

==== macOS ====
The search and lookup are performed in the contacts. If you wish to disable local contact lookup, go to system settings - Security & Privacy and disable the access to contacts for myapps.
=== Microsoft Office integration ===

The myApps platform services has a ''office presence provider'' that can provide the user's presence state to Office applications. See [[{{NAMESPACE}}:Concept_myApps_Office_Integration|myApps Office Integration]] for details.

This feature is installed by default. However, it can be disabled using the ''OFFICEPRESENCE'' MSI Parameter. Also, a check-mark is available in the setup dialog.

=== Call an external application for calls ===

Phone Apps (such as the phoneapp or softphone) can initiate the start of an external application when a new call appears (either incoming or outgoing). The actual spawning of the application is done by the myApps platform service. Also, the application properties (such as e.g. the executable's path) is configured in the myApps platform services (see [[#UI elements|Advanced settings]] in the ''UI elements'' section below).

A number of arguments can be passed to the application by substituting $-variables in the ''Parameter'' field:

; $n : phone number as dialed (called party number for outgoing calls) or received (calling party number for incoming calls)

; $N : called or calling party number in ''national'' format (e.g. 07031730090)

; $I : called or calling party number in ''international'' format (e.g. +497031730090)

: note that both $N and $I only work if $n includes both subscriber number and area code (e.g. 07031730090). Otherwise they are equal to $n

; $d : display name of peer (if known)

; $u : URI name of the peer (if available eg with a federation call)

; $c : conference id

: this is a globally unique ID for this call and may be used to relate the call to the ''guid'' found in the CallInfo structure in the [http://wiki.innovaphone.com/index.php?title=Reference10:SOAP_API#CallInfo SOAP-API] and [http://sdk.innovaphone.com/doc/appwebsocket/RCC.htm RCC-API ]. Also, corresponding [[Reference10:Call Detail Record CDR PBX|CDRs]] can be related using the ''event'' tag's ''conf'' attribute.
The start of an external application can be requested using the ''com.innovaphone.externalapps'' API.

Some setup examples are [[Howto:Integrate External Apps in innovaphone UC clients|shown here]].

=== Push ===

Mobile operating systems usually inhibit network operation of apps which run in the background or are closed by the user. This is done in order to reduce battery consumption. Unfortunately, this also stops such apps to maintain a registration by regularly sending ''keep alive'' messages to a server (in our case to the PBX). As a result, myApps will be disconnected from the PBX. When the PBX determines that there is an event for the application which needs a response, it needs to wake up the app using a dedicated channel provided by the operating system. This mechanism is know as ''push''. When running on iOS or Android, myApps supports ''push''.

For ''push'' to work, a [[{{NAMESPACE}}:PBX/Objects/Push|''push object'']] needs to be configured in the PBX . Also, it needs to be enabled on the mobile phone for the myApps app.
This mechanism is quite similar in v12 and v13, so you can refer to [[{{NAMESPACE}}:Concept_Push_Notifications_for_iOS_and_Android|the concept for push notifications for iOS and Android]] for more details.

Also, helpful hints can be found in [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]].

=== App Proxy ===

myApps runs further ''Apps'' (such as e.g. the ''phoneapp'') as a web page in an IFRAME of the browser myApps is running in. The App's page code is loaded either from the PBX or from an ''application platform'' (AP). This however would mean that the App's IFRAME would remain empty (a dead white screen) when the PBX or AP is not available. To make sure the App can start-up anyway, the myApps platform services feature the so-called ''App Proxy''. This is a caching proxy that caches all the App code so it is available even in case of network failure. When myApps runs in the context of the platform services, Apps are therefore not loaded from the App source directly, but from the local App proxy.

The cached files are stored in the PCs local file system in the <code>%LOCALAPPDATA%\innovaphone\myApps\appproxy</path></code>. There is no configuration required. However, if myApps seems to run with outdated or corrupt cached copies of the App, you can safely delete the entire directory.

=== Auto update ===

On Windows and on macOS, the myApps platform services can auto-update themselves to a common version. This is controlled by the [[{{NAMESPACE}}:PBX/Config/myApps#Launcher_Software_Update | ''Launcher Software Update'']] settings under ''PBX/Config/myApps'' in the PBX.

When myApps is started or the user logs in or myApps needs to re-connect to the PBX, the platform services will use the [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client API] to learn the desired version (''launcherUpdateBuild'', which is part of the API's ''model''). If this differs from the current version, the platform services will try to download the respective new version.

{
"mt": "ApiUpdate",
"apis": {
"com.innovaphone.client": {
"@client": {
"title": "innovaphone myApps",
"model": {
"launcher": true,
"launcherUpdateBuild": "134906",
"appStoreUrl": "http://store.innovaphone.com/release/download/"
}
}
}
}
}

The installation of the downloaded version is done by the ''innovaphonemyAppsUpdateService''. This service is installed and enabled during the initial installation of the myApps platform services. To disable auto-update, either leave the ''Launcher Software Update'' settings empty or set the service's start mode to ''disabled'' in the Windows ''services control panel''.

Note that on Windows the update service does not work on terminal servers. Administrators must do myApps base services updates using standard windows mechanisms.

Note that on macOS if myApps has been installed from the Apple Store it is assumed that auto update from the PBX is not desired and disabled therefore.

On Android/iOS/macOS updates can be downloaded from the respective app store.

The ''Devices'' app can not update software installed on Windows PCs directly. However, when the PBX is updated using an ''update job'' in the ''Devices'' App, the ''Launcher Software Update'' settings will be updated accordingly and hence the myApps base services will ultimately also be updated to the same version.

==== Auto update flow on Windows ====

* On start of myApps, myApps checks if an update is available and ready for installation
** if yes, the update is installed directly, without user interaction (a popup is shown during the installation)
** if not, myApps starts
* if an update is available while myApps is already running, an update notification will be shown which let's the user choose to install the update now or later (the notification will then popup again after one hour)

==UI elements ==
There are a few user interfaces provided by the platform services:
===tray-icon (Windows only) ===
::[[Image:myapps-tray.png|myapps-tray.png/|myapps-tray.png/]]
:Allows to
:* terminate myApps
:* toggle the ''autostart'' state
:* toggle the ''show in task bar'' state
:* open the trace folder
:
=== PBX connect form===
:: [[Image:myapps-connect.png|myapps-connect.png/|myapps-connect.png/]]
: Allows the user to specify the connect data for the PBX (i.e. IP address or DNS name)
:
=== Advanced settings===
::[[Image:myapps-settings0.png|myapps-settings0.png/|myapps-settings0.png/]]
::[[Image:myapps-settings.png|myapps-settings.png/|myapps-settings.png/]] [[Image:myapps-settings2.png|myapps-settings2.png/|myapps-settings2.png/]] [[Image:myapps-settings3.png|myapps-settings3.png/|myapps-settings3.png/]]

: Allows to modify various platform dependant settings (such as e.g. the hotkey selection on Windows)

== Interfaces ==
=== Provided APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm com.innovaphone.search] : access to local phone book entries by the [[#Local phonebook access|Local phonebook access]] component.
; [http://sdk.innovaphone.com/web1/com.innovaphone.launcher/com.innovaphone.launcher.htm com.innovaphone.launcher] : display of OS specific user notifications and receipt of related user actions
; com.innovaphone.notificationhandler : reports back click on a notification.
; com.innovaphone.externalapps : to start external applications, see [[#Call an external application for calls|Call an external application for calls]] above

=== Used APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm com.innovaphone.phone] : used to initiate new or manipulate existing calls by the [[#Hot keys|Hot keys]] and [[#URL handler|URL handler]] components.

; [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm com.innovaphone.chat] : used to start a new chat by the [[#URL handler|URL handler]] component.

; [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client] : the model is used to learn the update settings, see [[#Auto update|Auto update]] above

=== Protocols ===

; [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol] : used by apps to allocate RTP channels, see [[#RTP service for audio.2C video and data|RTP service for audio, video and data]] above

== Related App Services ==

none

== Known limitations ==
; Incoming call as banner on myApps for iOS : Since iOS 14 the iOS CallKit presents incoming calls as a banner leaving the original green answer button of myApps visible. Use only the blue button of the banner to accept the call or change iPhone Settings, App "Phone", "Incoming Calls" to "Full Screen" to hide the myApps user interface again during call answering.

; Call answer in speakerphone mode even with active Bluetooth headset on myApps for iOS : This causes unwanted speakerphone operation if the smartphone is used with a Bluetooth car audio system. The behaviour can be changed by selecting ''Bluetooth Headset'' in this setting:
:''iOS Settings->Accessibility->Touch->Call Audio Routing: Automatic / Bluetooth Headset / Speaker''
:''iOS Einstellungen->Bedienungshilfen->Tippen->Anrufaudioausgabe: Automatisch / Bluetooth-Headset / Lautsprecher''

; Windows Server 2016 (Windows 10 Build 1607) : windows just shows the first notification. Further notifications aren't displayed until the previous ones are removed from the notification center. Current windows builds do not show this behaviour anymore.

; Problems on Mac computers with Yealink USB headsets
: we have received reports that myApps quits unexpectedly on some Mac computers when a Yealink headset is plugged in. Unfortunately, we could not find out the cause yet. If you use Yealink USB headsets and have a similar issue, please open a support ticket and send myApps traces.

; Poly / Plantronics headset buttons only functional if myApps is started with Rosetta
: myApps macOS supports Apple M1/M2 hardware natively. However, the Poly / Plantronics headset SDK is only available for Intel platform and thus myApps needs to be started via Apple's Intel emulator Rosetta if a Poly / Plantronics headset is used. This is done with right-click on the myApps executable, ''Information'', ''Open with Rosetta''.

; Windows surface devices may not work correctly
: Chromium does not get touch keyboard events. USB Keyboards may not be recognized either.

= Installation =

== Windows ==

myApps platform services are installed on Windows using the .msi file found in the ''myApps Windows'' package from [https://store.innovaphone.com/release/download.htm store.innovaphone.com].

myApps can update itself automatically, see [[#Auto update|Auto update]] above.

=== MSI Parameters and install options ===

The MSI installer of myApps for Windows supports the following parameters and can be edited with [https://docs.microsoft.com/en-us/windows/win32/msi/orca-exe Microsoft Orca]. You can add your parameters in the table ''property''.

; SERVER (REG_SZ): the PBX's server address (without protocol like https://)
; OFFICEPRESENCE (REG_DWORD): '''false''' to disable presence integration in Microsoft Office
: this is also available as a check-mark when running the install manually

; DISABLEHEADSETS (REG_DWORD): '''true''' to disable headsets support, see [[#Device handling|Device handling]] above

; EXTERNALAPPS (REG_SZ): pre-define external applications, see [[#Call an external application for calls|Call an external application for calls]] above
: e.g. <code>"{""externalApps"":[{""id"":0,""name"":""Wireshark"",""path"":""C:\\Program Files\\Wireshark\\Wireshark.exe"",""param"":""test $I""}]}"</code>

; FORCERESTART (REG_DWORD): '''true''' (or any string ...) kills myApps during the installation and restarts it for the currently logged in user, if it was running

; DISABLELOCALHOST (REG_DWORD): '''true''' to disable use of '''localhost''' string to access the local webserver. Use '''127.0.0.1''' instead

; EXCLUDEINTERFACES (REG_SZ): some VPN interfaces are not detected by Windows as IF_TYPE_PPP or IF_TYPE_TUNNEL and therefore the '''media outside VPN''' setting is not taking effect. With this option interfaces can be pre-defined that will not be used for media. Interfaces must be comma separated
: e.g. <code>EXCLUDEINTERFACES="172,192.168,10.10"</code>

; FASTERDOWNLOADS (REG_DWORD): '''true''' to have faster downloads without artificially slowing down the download of an update (which is done to avoid audio lags if clients have slow networks).

Current settings are stored in the registry at <code>Computer\HKEY_CURRENT_USER\Software\innovaphone\myApps</code> or at <code>Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\innovaphone\myApps</code>

Boolean values like OfficePresence are stored in registry entries with type REG_DWORD and values 1 or 0. 0 disables the setting and 1 enables it.

== iOS ==

myApps platform services are installed on iOS by loading ''innovaphone myApps'' from the ''App Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist>

== macOS ==

myApps platform services might be installed directly from the Apple store. An installer package <code>myapps.pkg</code> and a disk image <code>myapps.dmg</code> is also available from the innovaphone app store. Install <code>myapps.pkg</code> by double-click on the file and follow the instructions of the installer. myApps becomes available in the Applications folder and can be opened by double-click. Or download and open <code>myapps.dmg</code> and double klick myApps. If desired integrate it into the app dock by right click, ''Options, Keep in the dock''.

If installed from the innovaphone app store, myApps can update itself automatically, see [[#Auto update|Auto update]] above.

If installed from the Apple store, macOS notifies about updates on the Apple store. myApps [[#Auto update|Auto update]] is disabled then.

If a clean-install of the client is necessary, the folder "/Users/username/Library/Containers/myapps" needs to be deleted. To be on the safe side also delete it from the trash bin.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist>

=== Preferences ===

macOS supports preference settings that can be set via a shell command or via Mac remote management

defaults write com.innovaphone.client-ios-14r1 server "PBX-server-URL"

The following parameters and can be set through this method:

; server: the PBX's server URL

=== Setting myApps as Default App for SIP-URLs ===

{| class="wikitable"
|defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add '{
LSHandlerURLScheme = sip;
LSHandlerRoleAll = "<CFBundleIdentifier>";
}'
|}

To find the “CFBundleIdentifier”, proceed as follows:
* In the Finder under “Applications”, search for the desired myApps client that you want to set as the default app.
* Right-click on “Show package contents” -> you will find the “CFBundleIdentifier” in the Info.plist file.

A restart of the MAC is required.

=== Using Sennheiser headsets ===
If you use Sennheiser headsets, you should also install the then-current <code>DSEA_SDK_v</code>''version''<code>.pkg</code> package, after you installed the myApps client. Without that, audio will still work, but not the controls on the headset. You will need to keep that up-to-date yourself, as it is not updated by myApps's auto-update function.

== Android ==

myApps platform services are installed on Android by loading ''innovaphone myApps'' from the ''Play Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying a property "server" with string value "pbx.example.com" in the MDM.

== IP270 ==
For configuration instructions, refer to the [[Reference16r1:Concept IP270|IP270 concept article]].

= Configuration =

== Server configuration ==
When opening myApps for the first time, the user is prompted for the Server. Usually only the hostname (DNS host name or IP address) needs to be configured.

But there are more options for special PBX configurations.

; Non-standard HTTPS port
: If the PBX uses a non-standard HTTPS port, it must be appended to the host name separated by a colon (<code>:</code>).
: Example: <code>pbx.example.com:4444</code> (expands to <code>https://pbx.example.com:4444/PBX0/APPCLIENT/appclient.htm</code>)
; DynPBX module name
: If the PBX is a DynPBX, the module id must be appended to PBX0 separated - (<code>/</code>).
: Example: <code>pbx.example.com/PBX0-1</code> (expands to <code>https://pbx.example.com/PBX0-1/APPCLIENT/appclient.htm</code>)
; Softphone physical location
: If user defined physical location shall be used for softphone, you can append it using a parameter <code>#phys=</code>.
: Example: <code>pbx.example.com#phys=slave</code> (expands to <code>https://pbx.example.com/PBX0/APPCLIENT/appclient.htm#phys=slave</code>)

Example 1: PBX pbx.example.com with standard configuration
pbx.example.com

Example 2: PBX slave.example with DynPBX module ID 1, HTTPS port 4444 and physical location master
slave.example.com:4444/PBX0-1#phys=master

=== HTTP proxy support ===

myApps platform services do support operation via HTTP proxy now. If one or more proxies have been configured in the network settings of the operating system for the active network connection, HTTP CONNECT tunnels are established.

On Windows user name and password can be specified for the tunnel servers as generic credentials in the credentials manager (Anmeldeinformationsverwaltung). The name of the credentials must be the tunnel server hostname.

On Android user name and password can be specified through Android ''Settings, Accounts'' by adding a myApps ''HTTP Proxy Credentials'' account. The name of the account must be the tunnel server hostname.

== Platform specific settings ==
When myApps runs under the myApps platform services, it will show various platform specific settings as part of its ''burger menu'', so the user can set them. See ''Advanced settings'' in [[#UI elements|UI elements]] above.

Some options can also be set globally for all myApps clients in the PBX's [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps ''Client Settings'']]
{|
! style="text-align: left; font-weight: bold" | Option

! style="text-align: left; font-weight: bold" | Description

! style="text-align: left; font-weight: bold" | Where to set

!
! style="text-align: left; font-weight: bold"| Availability
|-

| || || User menu || PBX ''Client Settings'' || Windows || iOS || Android || macOS
|IP270<ref>myApps-IP270 offers device specific settings explained in [[Reference16r1:Concept IP270|IP270 concept article]]</ref>
|-
| Autostart || Launch myApps on login || ✔ ||✔ ||✔ || ✗ || ✗ || ✔
|✗
|-

| Appear offline after || controls after which idle time a user is considered ''inactive''. See [[#User activity|User activity]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔
|✗
|-

| Hotkeys || Hotkeys for call dial, accept, reject. See [[#Hot keys|Hot keys]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔
|✗
|-

| Docking || Docking mode (left, right, none). See [[#???|??]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✗
|✗
|-

| Desktop notifications|| Turn on/off platform notifications. See [[#Notifications| Notifications]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔
|✗
|-

| VPN || Disable VPN address for ICE candidate selection. See [[#RTP ports| RTP ports]] above || ✔ ||✔ ||✔ || ✗ || ✔ || ✔
|✗
|-

| Show in taskbar|| Show myApps in the taskbar in addition to it's tray icon. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗
|✗
|-

| Log flags || turn on/off certain trace levels. See [[#Troubleshooting|Troubleshooting]] below. || ✔ ||✔ ||✔ || ✔ || ✔ || ✔
|✔

|-

| External applications || define the applications available for Apps to be started. See [[#Call an external application for calls|Call an external application for calls]] above. || ✔ ||✗ ||✔ || ✗ || ✗ || ✔
|✗
|-

| Ring in headset || send ring tone for incoming to headset instead of loudspeaker. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗
|✗
|}
<references/>

== Start parameters for Windows ==

On Windows, it is not possible to pass start parameters from the [https://www.chromium.org/developers Chromium documentation] to the myApps process.

== OS Settings for Windows ==
Windows settings can influence the display of ''Desktop notifications''. See [https://support.microsoft.com/en-us/help/4028678/windows-10-change-notification-settings Change notification settings in Windows 10/11] for details.

=== Windows 11 ===

* Windows 11 has a feature "do not disturb". This hides notifications if enabled.
* Windows 11 has a feature "focus". This enables "do not disturb" and thus hides notifications too.
* Windows 11 has priority settings for notifications. Ensure that VoIP notifications for calls are allowed any maybe also include myApps as an App which is allowed to show notifications.

== OS settings for Android ==
; Events : The appearance of notifications can be controlled here.

; Call accounts : For proper incoming call signaling, the call account ''myApps'' needs to be enabled. Note that on Samsung smartphones the call account switch likely toggles back and a few tries may need to be done until it persists. Please double-check the state.

; Preferred Calling Account : Choose which calling account (myApps/SIM/..) should be used for outgoing calls initiated from within the native phone app / phone book.

; Background data, unlimited data usage : Grant background data use to enable ''myApps'' to connect to the PBX immediately on an incoming call.

; Overlaying : This setting is not needed if call account ''myApps'' has been enabled. Should there be a reason for not enabling call account ''myApps'', the permission for overlaying needs to be granted on Android 10 or higher for proper call signaling.

Note: If no SIM card is installed some Android smartphones exhibit a problem dialing from the smartphone contacts. The contacts app shows a choice ''Select SIM card for this call'' but all possible dialers are greyed out. In this case make myApps the default phone app in Android settings ''Apps, Default apps, Telephony''.

== OS settings for iOS ==
; Notifications : The appearance of notifications can be controlled in iOS ''Settings, myApps''.

== OS settings for macOS ==

; Notifications : The appearance of notifications can be controlled in macOS ''Preferences, Notifications, myApps''.

=Troubleshooting=

myApps platform services can write various traces for debugging. Trace can be turned on and off selectively in the [[#Advanced settings|Advanced settings]].

The following trace flags can be set:

(''Recommended trace options are: '''App, Browser, ICE, TURN, Signaling and Audio'''. Please do not activate other flags unless innovaphone support says otherwise'')

{|
!style="text-align: left; font-weight: bold" | Abbreviation

!style="text-align: left; font-weight: bold" |code

!style="text-align: left; font-weight: bold" | description

|-
| App||0x000000001|| logs from the App Service itself
|-
| DNS||0x000000008|| logs DNS requests and results
|-
| HTTP client||0x000000080|| http client logs
|-
| TLS||0x000000400|| TLS logs
|-
| TCP||0x000000800|| TCP logs
|-
| LDS||0x000001000|| local domain sockets
|-
| WebSocket client||0x000004000|| logs outgoing websocket connections
|-
| App WebSocket||0x000008000|| logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
|-
| UDP||0x000200000|| UDP logs
|-
| DTLS||0x000400000|| logs DTLS handshake and messages
|-
| Media||0x000800000|| logs media events
|-
| Media channel||0x001000000|| logs RTP/SCTP media connections
|-
| ICE||0x002000000|| logs ICE messages between peers
|-
| TURN||0x004000000|| logs TURN messages between peers
|-
| AppSharing||0x008000000|| logs AppSharing connection
|-
| Audio||0x010000000|| logs Audio connection and headset events
|-
| Video||0x020000000|| logs video connection and webcam events
|-
| Browser||0x040000000|| logs Chromium events
|-
| AppProxy||0x080000000|| logs requests which are proxied between the local webserver and the remote server
|-
| Webserver ||0x200000000|| enables webserver specific logs
|-
| Browser Console ||0x400000000|| logs browser console events
|-
| Signaling||0x800000000|| enables logs in the signaling module for debugging calls
|}
''code'' can be or'ed and used as value for the ''Log flags'' field in [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps/Client Settings]].

; Windows :On Windows, traces are written to the <code>%LOCALAPPDATA%\innovaphone\myApps</code> directory. If you start myApps with --log-size as parameter, you can define the maximum size of a log file (e.g. --log-size=100000000 would be 100MB for each file)

:* myApps-''date-time''.txt : main log file for the platform services

:* myAppsOutlookSearch-''date-time''.txt : log file for the Outlook phone book access

:* myAppsHookController-''date-time''.txt : log file for the hot-key interceptor (see [[#Hot keys|Hot keys]])

; :myApps update installation traces are written to the <code>%windir%\temp\</code> directory.
:* myAppsInstall.txt: MSI installation file

; :myApps update service traces are written to the <code>%ProgramData%\innovaphone\myAppsUpdateService</code> directory.
:* myAppsUpdateService-''date-time''.txt: myApps update service traces

;Android : traces can be sent by e-mail.
: also, an Android device might also be connected to a PC via an USB cable to get the traces. The files can be found in <code>Android/data/com.innovaphone.clientandroid/files</code>

; iOS : traces can be sent by e-mail.

; macOS : traces can be sent by e-mail.
: also, the files can be found in <code>~/Library/Containers/com.innovaphone.client-ios/Data/Documents/</code>. Press ''Alt+N'' followed by space to get tilde ''~''.

; IP270 : Refer to the [[Reference16r1:Concept IP270#Troubleshooting|IP270 concept article section troubleshooting]].

= Known Problems =
[[:Category:Problem myApps platform services|Known Problems]]

= Related Articles =
* [[{{NAMESPACE}}:Concept_myApps]]
* [[{{NAMESPACE}}:Concept_myApps_Redundancy|Concept myApps Redundancy]]
* [[{{NAMESPACE}}:Concept_myApps_Office_Integration|Concept myApps Office Integration]]
* [[{{NAMESPACE}}:Concept_myAPPs_Search_in_local-Outlook_Contacts|Concept myAPPs Search in local Outlook Contacts]]
* [[{{NAMESPACE}}:Call_Detail_Record_CDR_PBX|Call Detail Records]]
* [[{{NAMESPACE}}:Concept Push Notifications for myPBX iOS and Android|Concept Push Notifications for myPBX iOS and Android]]
* [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reference16r1:PBX/Config/myApps]]
* [[{{NAMESPACE}}:Concept_IP270|IP270 concept article]]
[[Category:Concept myApps platform services]]

Reference15r1:Concept myApps platform services

2026-03-26T08:12:39Z

Dde: /* MSI Parameters and install options */

[[Category:Concept|myApps]]

myApps platform services provide various operating system specific services which can be used by other ''Apps'' running in the [[{{NAMESPACE}}:Concept myApps|myApps client]]. Those services typically are not available in the browser's JavaScript environment and hence must be implemented in native platform code. Therefore, the platform services are installed as native executable on the respective platform.

When myApps is started in a web browser (and hence has no access to the platform services), some Apps will use [https://en.wikipedia.org/wiki/WebRTC WebRTC] services implemented by the browser instead. For ease of reference, features available in this scenario are also described here.

On windows, the platform services also come with their own web browser in which the myApps web App will be started then. This browser is based on google's [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium] open source software.
= Applies To =

* [[{{NAMESPACE}}:Concept myApps|myApps]]
* myApps for Windows
* myApps for macOS
* myApps for iOS
* myApps for Android

* myApps Web App (WebRTC)
version 14r2

=Features=
Not all features are available or required on all platforms.
{|
! style="text-align: left; font-weight: bold" | Feature

! style="text-align: left; font-weight: bold" | Description

! style="text-align: left; font-weight: bold"| Availability
|-

| || || Windows || iOS || Android || macOS || Browser<ref>This refers to the myApps web application running in a browser with no platform services available</ref>

|-
| audio || manage local audio devices to record and playback audio conversations || ✔ || ✔ || ✔ || ✔ || ✔ (audio available but devices managed by web browser)
|-

| video || manage local displays and cameras to capture and render video live stream || ✔ || ✔ || ✔ || ✔ || ✔ (video available but devices managed by web browser)

|-

| ringer || manage local ringing device || ✔ || ✔ || ✔ || ✔ || ✔
|-

| application sharing

|-

|   presenter || share an application || ✔ || ✗ || ✔ || ✔ || ✔
|-

|   consumer || view an application shared by the peer || ✔ || ✔ || ✔ || ✔ || ✔

|-

| hot keys || capture key presses for quick invocation of phone apps (e.g. dial selected number) || ✔ || ✗ || ✗ || ✔ || ✗
|-
| tel: and sip: URI handler || intercept clicks on tel: and sip: links in web sites to invoke phone apps || ✔ || ✔ || ✔ || ✔ || ✗

|-
| user activity || set presence state according to user activity || ✔ || ✗ || ✗ || ✔ || ✔<ref>limited, see [[#User activity|User activity]] below</ref>

|-

| docking || myApps can be docked persistently to the right or left edge of your screens || ✔ || ✗ || ✗ || ✗ || ✗

|-

| multi-windowing|| Apps can be launched in separate windows|| ✔ || ✗ || ✗ || ✔ || ✗

|-

| recording|| Calls can be recorded to recording app|| ✔ || ✔ || ✔ || ✔ || ✗

|-
| notifications || ||
|-
|   display notifications || display notifications with OS standard mechanism || ✔ || ✔ || ✔ || ✔ || ✔
|-
|   push notifications || receive push notifications while myApps is not running || ✗ || ✔ || ✔ || ✔ || ✔<ref>The browser needs to be running in order to receive push notifications.</ref>
|-
|   chat and apps || display notifications for chat and other apps || ✔ || ✔ || ✔ || ✔ || ✔
|-
|   calls || display notifications for incoming calls || ✔ || ✔ || ✔ || ✔ || ✗<ref>Call notifications are only displayed locally while the phone or softphone app is started.</ref>
|-

| phone book access || access local phone book || ✔ || ✔ || ✔ || ✔ || ✗
|-
| office presence provider || maps PBX presence state to Microsoft office presence state || ✔ || ✗ || ✗ || ✗ || ✗
|-

| external application start || start arbitrary external applications for calls || ✔ || ✗ || ✗ || ✔ || ✗

|-

| app proxy|| a caching proxy that provides app persistence || ✔ || ✔ || ✔ || ✔ || ✗

|-

| auto update || automatically updates myApps platform services to the same version the PBX has || ✔ || ✔ || ✗ || ✔ || ✔<ref>The then-current web app is always loaded from the PBX upon startup and hence up-to-date by definition</ref>
|-

| three party conference || initiate 3-pty-conference using Softphone-App || ✔ || ✔ || ✔ || ✔ || ✗

|-
| exclude VPN || disable use of VPN connections for audio and appsharing || ✔ || ✔ || ✔ || ✔ || ✗

|}

<references/>

=Requirements=
* innovaphone PBX 14r2 and up

== Hardware ==
Recommended hardware requirements
* Processor: Dual-core 2Ghz or higher
* RAM: 4 Gb

== myApps for Windows ==
* Windows 10 and up
* Windows Server 2016 and later versions

=== 32 & 64 bit Windows ===
* 32 bit Windows: install the myAppsSetup32.msi from the App Store
* 64 bit Windows: install the myAppsSetup.msi from the App Store
** the 64 bit variant still installs into Program Files (x86), as the main myApps.exe is still a 32bit application
** the 64 bit variant just contains an additional 64 bit binary for the outlook search

=== Windows N editions ===

Windows N editions are missing the ''Media Feature Pack'' which is pre installed on other Windows versions.

Please install the pack from [https://www.microsoft.com/en-us/software-download/mediafeaturepack Microsoft (Windows 10 pack)] before you install myApps. The installer will check if the file <code>C:\Windows\SysWOW64\mfplat.dll</code> exist on your system.

Make sure to install the correct pack depending on your Windows version! There are different packs for Windows 10 1703, 1803, 1809 and 32bit or 64bit etc.

NB: Sometimes the myApps installation will not work even though the media pack is already installed. This is because the installer has no read access to check if the package is already installed. If the above-mentioned file exists and the installer asks to install the Windows Media Feature Pack nevertheless, you have to start the myApps install with administrative rights.

=== Terminal Server environments ===

Audio driver was removed if myApps discovers that it is running in a terminal server environment like Citrix.

The audio driver is needed for the Softphone App but the Softphone App should not use an audio driver at the server side because the audio devices are plugged locally and there would be a delay sending and receiving audio data with the server.

If a customer wants to use the Softphone App at the server side he needs to make use of the myApps Plugin for virtual desktops solution:

[[{{NAMESPACE}}:MyApps_Plugin_for_Virtual_Desktops|Reference15r1:MyApps_Plugin_for_Virtual_Desktops]]

== myApps for macOS ==
* macOS 10.13 or higher

== myApps for iOS ==
* iOS 12 or higher

== myApps for Android ==
* Android 6.0 or higher. Android 6.x may need an update of the Chrome browser.

= Licenses =
* No license needed for myApps platform services

= Overview =
myApps platform services is a native executable that is installed using the standard mechanisms on the respective operating system. It provides various advanced services which can be used by the myApps web client code as well as the Apps running in the myApps context.

Also, on Windows, the platform services come with their own, dedicated browser to run myApps in. This browser is based on [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium]. On iOS, macOS and Android, it is based upon native embedded web view facilities (such as WKWebView) instead.
== Components ==

=== RTP service for audio and appsharing ===
The RTP service provides audio and appsharing as a video stream. VoIP RTP endpoints (e.g. for softphones). It supports STUN, TURN, ICE, SRTP, DTLS. Note however that unlike WebRTC, these endpoints do not ''require'' ICE and DTLS. In other words, they can communicate also with non-compliant (i.e. older) VoIP devices.

Note that the available capabilities when not running the myApps platform services depend on the used browser's WebRTC implementation. See your browser documentation for details.

Apps can request RTP channels using the [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol]'s ''AllocChannel'' message.

===== RTP ports=====

{|

| audio || 50000 -> 50099

|-

| video (app sharing) || 50100 -> 50199

|}

The RTP service will enumerate all local interfaces and create local HOST candidates for ICE. There is an option however to disregard VPN interfaces (more precisely such interfaces with type of ''IF_TYPE_PPP'' or ''IF_TYPE_TUNNEL''). This can eliminate quality issues when RTP data is transmitted through TCP based VPN tunnels.

SRFLX and RELAY candidates are obtained using the STUN and TURN server configuration passed by the App (e.g the ''softphone'' App) as part of the ''AllocChannel'' request.
<code>{"mt":"AllocChannel","channel":"81429cba-396d-43de-8a76-ec020ba8796e","iceServers":[{"urls":"turn:myturn.domaincom:4077?transport=udp","username":"turnuser","credential":"pwd","credentialType":"password"},{"urls":"stun:mystun.domain.com:4077"}],"dn":"Foo Bar","type":"RemoteRtp","kind":"video"}</code>

===== Codecs =====

The installed myApps launchers provide codecs that can be used by softphone apps for media streams. When running in a web browser the codecs depend on the browser version and operating system. See the documentation of your browser for details.

The following codecs are supported:

{|
!style="text-align:left;width:100px;"|Codec
!style="width:100px"|Windows-Launcher
!style="width:100px"|Android
!style="width:100px"|iOS
!style="width:100px"|macOS
!style="width:100px"|Firefox (Browser)
!style="width:100px"|Chrome (Browser)
!style="width:100px"|Edge (Browser)
!style="width:100px"|Safari (Browser)
!style="width:100px"|Opera (Browser)
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Audio
|-
|G711A
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G711u
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G722
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G729
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729A
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729B
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729AB
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|[https://caniuse.com/#search=Opus OPUS-NB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|[https://caniuse.com/#search=Opus OPUS-WB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Video
|-
|[https://caniuse.com/#search=VP8 VP8]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|-
|[https://caniuse.com/#search=VP9 VP9]
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|-
|[https://caniuse.com/#search=H264 H264]
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Application Sharing
|-
|Share
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|Watch
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|}

''* small presentation only'' 
''** only for 1:1 calls, not for conferences

===== Video capture =====

The default resolution for video capture is 1920x1080 if available. Otherwise, 1280x720, 640x480, 352x288 or 320x240 will be used. The frame rate is 30 fps if available, otherwise 15 fps. The resulting average bandwidth could reach 1 Mbps.

===== Application sharing =====

Screen content will be transmitted as video stream by the presenter

===== Device handling =====

The RTP service enumerates microphones, loudspeaker, cameras and ringing devices and notifies apps when devices come and go. It is up to the apps using the devices to store preferences.

The RTP service also enables some extended features (such as hook switch or volume control) for supported USB headsets or Bluetooth headsets connected to myApps.
The supported headset-SDKs determine which headset vendors are recommended to be used with the myApps softphone app. 

For this to work, the following vendor specific development kits are integrated in our myApps client. Be aware that the SDK are updated within our Service release :

{| class="wikitable"
|-
! SDK Vendor !! Supported OS !! SDK Version !! innovaphone Service Release
|-
| Jabra|| MacOS || 1.12.2.0 || 13r3sr9
|-
||| Windows || 1.12.2.0 || 13r3sr10
|-
| Epos ''(formerly Sennheiser)'' || MacOS || 12.4.0.5478 || 14r1sr3
|-
||| Windows || n.a. - [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|to be installed separately]]|| 13r3sr10
|-
| Poly ''(formerly Plantronics)'' || MacOS || 3.25.53799.37131 || 13r3sr9
|-
||| Windows || 3.25.53800.37131 || 13r3sr10
|-
| Yealink || MacOS || 3.1.1.20 || 14r1sr3
|-
||| Windows || 3.1.1.20 || 14r1sr3
|}

Notes:
* It is possible to inhibit the start of the Sennheiser SDK (SenncomSDK.exe) using the <code>DISABLEHEADSETS</code> directive of the installer (see [[#MSI Parameters and install options| MSI parameters]] below).

* Starting with V13r3sr10, the Epos-SDK needs to be installed separately using the Epos Connect software to ensure full compatibility between current Epos headset models and native myApps-Windows client. For details [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|refer to this article]].


===== Ring tones =====

Ring tones can be played. Apps can choose the tone from a pre-defined list of ring tones.

On Windows, custom ring tones can be uploaded as .mp3 files to the <code>ringtones</code> sub-directory of myApps' roaming directory (which usually is in <code>%appdata%\innovaphone\myApps\ringtones</code>).

On Android, custom ring tones can be added to the system via Android settings.

On iOS, custom ring tones can be uploaded as .mp3 files to the <code>Ringtones</code> subdirectory of the myApps file share that is available in iTunes if the iPhone has been connected via USB.

On macOS, custom ring tones can be uploaded as .mp3 files to <code>~/Library/Containers/com.innovaphone.client-macos/Data/Documents/Ringtones</code>.

===== Debugging =====
For extended debugging, turn on the ''Audio'', ''Media'' and ''AppSharing'' traces in myApps.

=== Hot keys ===
On Windows and macOS systems, myApps platform services can listen for hot keys and invoke certain functions. Invocation is done by sending API messages to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

The hot keys can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below. Any of the function keys F1 to F11 (optionally combined with up to two modifier keys ''alt'', ''ctrl'', ''shift'' or ''win'') can be chosen for each function. If you do not want to start the call with "Hotkey+Enter" because you would have to wait for the focus, the hotkey can also be pressed twice and the number is dialled directly.

; dial selected number : Initiates a call using the currently selected text as target.

: A ''PrepareCall'' message with the ''text'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":"mt":"PrepareCall","text":"13","adjust":true}}</code>

; accept call : Accepts a currently alerting call.

: A ''ConnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"ConnectCall"}}</code>

; reject/disconnect call : Rejects a currently alerting call or disconnects an active call.

: A ''DisconnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"DisconnectCall"}}</code>

=== URL Handler ===

On Windows systems, two URI-handler are installed with the myApps platform services. Windows will call up this URI handler when a user clicks on an appropriate link, for example in a web site.

The handler will the send an API message to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

; tel URI : call a number, e.g. <code>tel:4711</code>

: A ''PrepareCall'' message with the ''num'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","num":"4711","adjust":true}}</code>
; sip URI : call a SIP name, e.g. <code>sip:zkl@innovaphone.com</code>

: A ''PrepareCall'' message with the ''sip'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","sip":"zkl@innovaphone.com","adjust":true}}</code>
; im URI : start chat with SIP name, e.g. <code>im:zkl@innovaphone.com</code>

: A ''StartChat'' message with the ''sip'' argument set to the selected text will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm ''com.innovaphone.chat'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.chat","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartChat","sip":"zkl@innovaphone.com"}}</code>

On macOS systems myApps might be made the default application to handle tel URI e.g. <code>tel:4711</code> via Apple FaceTime. Open the "FaceTime" menu "Settings..." and select myApps as "Default for phone calls".

On iOS ''tel'' URIs are always dialed via GSM. Therefore myApps iOS also reacts to URI schemes ''com.innovaphone.tel'', ''com.innovaphone.sip'' and ''com.innovaphone.im'', e.g. <code><nowiki>com.innovaphone.tel:4711</nowiki></code>, <code><nowiki>com.innovaphone.sip:zkl@innovaphone.com</nowiki></code>, <code><nowiki>com.innovaphone.im:zkl@innovaphone.com</nowiki></code>.

=== User activity ===
On Windows and macOS systems, the myApps platform services can monitor user keyboard/mouse activity and change the user's presence state after a certain amount of inactivity. The timeout can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below.

myApps will then send a [https://sdk.innovaphone.com/doc/appwebsocket/myApps.htm#SetUserActivity''SetUserActivity''] message to the PBX using the ''myApps'' protocol.

: <code>{"mt":"SetUserActivity","inactive":true}</code>

This will change the ''status'' property of the ''im:'' contact for the user's own presence and hence result in a presence update from the PBX to myApps

: <code>{"mt":"UpdateOwnPresence","presence":[{...},{"contact":"im:","activity":"","status":"closed"}]}</code>
The ''closed'' status is reflected in the grey status color when displaying a contact [[Image:myapps-inactive.png|myapps-inactive.png/|myapps-inactive.png/]].

On iOS and Android, the state is set to ''inactive'' as soon as the App is brought to background.
When myApps platform services are not available (i.e. when running the web application in a browser solely) a limited user activity monitoring is available: the state is set to active when the web page is not used for more than 5 minutes.

=== Recording ===

The new launcher offers the possibility to record the audio of incoming and outgoing calls. In order to activate that functionality the URL of the recording instance must be configured in either the PBX (PBX->myApps->Config: Recording URL) or the softphone App (Settings->Audio Recording (URL))

[[Image:PBX-Recording-Settings.png|pbx-recording-settings.png/|pbx-recording-settings.png/]] [[Image:Recording-Softphone-Settings.png|recording-softphone-settings.png/|recording-softphone-settings.png/]].

As long as that URL is configured the audio data of all calls are stored as pcap-files under that URL.
If the URL points to a CF device in the PBX, write access must be granted for that URL (PBX->Services->HTTP->Server:Public compact flash access) and if the URL points to the recording app, the files can be accessed via the recording app [[{{NAMESPACE}}:Concept_App_Service_Recordings|recording]].

Under PBX->myApps the administrator can set a certain default behaviour of the audio recording like whether or not the recording should start automatically at the beginning of the call (Recording by Default ON/OFF), only calls with external numbers should be recorded (Record external calls only) or whether or not the user should be able to start/stop the recording himself (Allow user incall recording control). Except for the last parameter these parameters can also be modified by the user in its softphone settings if the administrator doesn't set the FORCE flag.

If the user was allowed by the admin to control the recording a recording switch is active during the call when the "Media" Panel is opened. There the audio recording may be stopped and continued at will. A red recording notice is shown in the top right corner when the recording actually takes place.

[[Image:Recording-incall-switch.png|recording-incall-switch.png/|recording-incall-switch.png/]]

=== Notifications ===

The myApps platform services can use the OS specific notification mechanism (e.g. ''desktop notifications'' on Windows) to display messages (e.g. ''incoming new chat message'') to the user.

Note that the actual rendering of the notification is under control of the OS. Therefore, myApps must be allowed to show notifications and its appearance can be restricted by OS native settings.

==== Microsoft Windows Notifications ====

Microsoft Windows Server editions (2016, 2019, 2022) are just capable of showing a single ''IncomingCall'' notification at the same time (we couldn't find a workaround for this limitation). 
An ''IncomingCall'' notification is visible the whole time instead of being moved to the action center after a certain time. 
 
A notification about a missed call uses the ''IncomingCall'' type so that this notification is visible until the user returns. 
Due to the above limitation, on a new arriving call such a missed call notification is transformed to a default notification which will be moved to the action center automatically. 
 
On non server editions, you can have multiple IncomingCall notifications at the same time (so two parallel incoming calls will be indeed notified at the same time), but the missed call notification handling is the same on both platforms!

Thus there will be always just '''one''' missed call notification visible and previous missed calls can be found inside your action center!

To see myApps notifications, ensure:
* System -> Notifications
** enable notifications
** disable "Do not disturb" or allow myApps as priority application while "Do not disturb" is active
** enable notifications for myApps in the list of applications
* System -> Focus
** if a focus session is active and the "Do not disturb" is activated during a focus session, make sure that myApps is a priority application (see above)

==== macOS Notifications ====
Notifications are the same as on Windows.
The difference is, that for macOS, notifications need to be allowed in the system settings.
Go to Notifications - myApps, select Banner and enable all check marks.

=== Local phonebook access ===
'''Contact Search:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm ''com.innovaphone.search'' API]]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Search'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{"mt":"Search","type":"contact","search":"john doe"},"apiId":"com.innovaphone.search"}</code>
Search results are delivered as ''SearchInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{"mt":"SearchInfo","relevance":2000,"adjust":true,"type":"contact","contact":{"givenname":"John","sn":"Doe","company":"ACME","position":"Head of everything","telephonenumber":["11111","22222"],"homephone":["+4944444","33333"],"mobile":["+49 (123) 55555"]}},"api":"com.innovaphone.search"}</code>

'''Reverse Lookup:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.phonelookup/lib1_api_phonelookup.htm ''com.innovaphone.phonelookup'' API]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Lookup'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{ mt: "Lookup", prefixIntl: "000", prefixNtl: "00", prefixExt:"0", area: "7031", country: "49", lookup: "0004970311234567" },"apiId":"com.innovaphone.lookup"}</code>

Search results are delivered as ''LookupInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{mt: "LookupInfo", dn: "Jake Blues", contact: { telephonenumber: ["0004970311234567"], givenname: "Jake", sn: "Blues", company: "Blues Brothers" </code>

==== Windows ====
On Windows, the search and lookup are performed in all of the user's Outlook contact folders. As opposed to the search implemented in the ''Contacts'' and ''Users'' App, all items are returned which match any of the search words (i.e. searching for ''a b'' will return items matching either ''a'' or ''b'').

; searched properties : firstname, lastname
; returned properties : Following Outlook contact phone number properties are returned (if available):

:* OFFICE_TELEPHONE_NUMBER as ''telephonenumber''
:* OFFICE2_TELEPHONE_NUMBER as ''telephonenumber''
:* HOME_TELEPHONE_NUMBER as ''homephone''
:* HOME2_TELEPHONE_NUMBER as ''homephone''
:* MOBILE_TELEPHONE_NUMBER as ''mobile''
:* BUSINESS_FAX_NUMBER as ''facsimiletelephonenumber''
Note that contact information is cached in the search provider. Updated contacts may therefore become effective after a while only.
Outlook search will create its own trace file <code>myAppsOutlookSearch-</code>''date-time''<code>.txt</code> in the standard trace directory.

This search provider is always installed and can be disabled. There is no need (nor possibility) to enable it in the ''Apps'' tab of the PBX's user object. Also, no ''App'' object needs to be created for it.

==== Android/iOS ====
The search and lookup are performed in the contacts.

==== macOS ====
The search and lookup are performed in the contacts. If you wish to disable local contact lookup, go to system settings - Security & Privacy and disable the access to contacts for myapps.

=== Microsoft Office integration ===

The myApps platform services has a ''office presence provider'' that can provide the user's presence state to Office applications. See [[{{NAMESPACE}}:Concept_myApps_Office_Integration|myApps Office Integration]] for details.

This feature is installed by default. However, it can be disabled using the ''OFFICEPRESENCE'' MSI Parameter. Also, a check-mark is available in the setup dialog.

=== Call an external application for calls ===

Phone Apps (such as the phoneapp or softphone) can initiate the start of an external application when a new call appears (either incoming or outgoing). The actual spawning of the application is done by the myApps platform service. Also, the application properties (such as e.g. the executable's path) is configured in the myApps platform services (see [[#UI elements|Advanced settings]] in the ''UI elements'' section below).

A number of arguments can be passed to the application by substituting $-variables in the ''Parameter'' field:

; $n : phone number as dialed (called party number for outgoing calls) or received (calling party number for incoming calls)

; $N : called or calling party number in ''national'' format (e.g. 07031730090)

; $I : called or calling party number in ''international'' format (e.g. +497031730090)

: note that both $N and $I only work if $n includes both subscriber number and area code (e.g. 07031730090). Otherwise they are equal to $n

; $d : display name of peer (if known)

; $u : URI name of the peer (if available eg with a federation call)

; $c : conference id

: this is a globally unique ID for this call and may be used to relate the call to the ''guid'' found in the CallInfo structure in the [http://wiki.innovaphone.com/index.php?title=Reference10:SOAP_API#CallInfo SOAP-API] and [http://sdk.innovaphone.com/doc/appwebsocket/RCC.htm RCC-API ]. Also, corresponding [[Reference10:Call Detail Record CDR PBX|CDRs]] can be related using the ''event'' tag's ''conf'' attribute.
The start of an external application can be requested using the ''com.innovaphone.externalapps'' API.

Some setup examples are [[Howto:Integrate External Apps in innovaphone UC clients|shown here]].

=== Push ===

Mobile operating systems usually inhibit network operation of apps which run in the background or are closed by the user. This is done in order to reduce battery consumption. Unfortunately, this also stops such apps to maintain a registration by regularly sending ''keep alive'' messages to a server (in our case to the PBX). As a result, myApps will be disconnected from the PBX. When the PBX determines that there is an event for the application which needs a response, it needs to wake up the app using a dedicated channel provided by the operating system. This mechanism is know as ''push''. When running on iOS or Android, myApps supports ''push''.

For ''push'' to work, a [[{{NAMESPACE}}:PBX/Objects/Push|''push object'']] needs to be configured in the PBX . Also, it needs to be enabled on the mobile phone for the myApps app.
This mechanism is quite similar in v12 and v13, so you can refer to [[{{NAMESPACE}}:Concept_Push_Notifications_for_iOS_and_Android|Reference14r2:Concept_Push_Notifications_for_iOS_and_Android]] for more details.

Also, helpful hints can be found in [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]].

=== App Proxy ===

myApps runs further ''Apps'' (such as e.g. the ''phoneapp'') as a web page in an IFRAME of the browser myApps is running in. The App's page code is loaded either from the PBX or from an ''application platform'' (AP). This however would mean that the App's IFRAME would remain empty (a dead white screen) when the PBX or AP is not available. To make sure the App can start-up anyway, the myApps platform services feature the so-called ''App Proxy''. This is a caching proxy that caches all the App code so it is available even in case of network failure. When myApps runs in the context of the platform services, Apps are therefore not loaded from the App source directly, but from the local App proxy.

The cached files are stored in the PCs local file system in the <code>%LOCALAPPDATA%\innovaphone\myApps\appproxy</path></code>. There is no configuration required. However, if myApps seems to run with outdated or corrupt cached copies of the App, you can safely delete the entire directory.

=== Auto update ===

On Windows and on macOS, the myApps platform services can auto-update themselves to a common version. This is controlled by the [[{{NAMESPACE}}:PBX/Config/myApps#Launcher_Software_Update | ''Launcher Software Update'']] settings under ''PBX/Config/myApps'' in the PBX.

When myApps is started or the user logs in or myApps needs to re-connect to the PBX, the platform services will use the [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client API] to learn the desired version (''launcherUpdateBuild'', which is part of the API's ''model''). If this differs from the current version, the platform services will try to download the respective new version.

{
"mt": "ApiUpdate",
"apis": {
"com.innovaphone.client": {
"@client": {
"title": "innovaphone myApps",
"model": {
"launcher": true,
"launcherUpdateBuild": "134906",
"appStoreUrl": "http://store.innovaphone.com/release/download/"
}
}
}
}
}

The installation of the downloaded version is done by the ''innovaphonemyAppsUpdateService''. This service is installed and enabled during the initial installation of the myApps platform services. To disable auto-update, either leave the ''Launcher Software Update'' settings empty or set the service's start mode to ''disabled'' in the Windows ''services control panel''.

Note that on Windows the update service does not work on terminal servers. Administrators must do myApps base services updates using standard windows mechanisms.

Note that on macOS if myApps has been installed from the Apple Store it is assumed that auto update from the PBX is not desired and disabled therefore.

On Android/iOS/macOS updates can be downloaded from the respective app store.

The ''Devices'' app can not update software installed on Windows PCs directly. However, when the PBX is updated using an ''update job'' in the ''Devices'' App, the ''Launcher Software Update'' settings will be updated accordingly and hence the myApps base services will ultimately also be updated to the same version.

==== Auto update flow on Windows ====

* On start of myApps, myApps checks if an update is available and ready for installation
** if yes, the update is installed directly, without user interaction (a popup is shown during the installation)
** if not, myApps starts
* if an update is available while myApps is already running, an update notification will be shown which let's the user choose to install the update now or later (the notification will then popup again after one hour)

==UI elements ==
There are a few user interfaces provided by the platform services:
===tray-icon (Windows only) ===
::[[Image:myapps-tray.png|myapps-tray.png/|myapps-tray.png/]]
:Allows to
:* terminate myApps
:* toggle the ''autostart'' state
:* toggle the ''show in task bar'' state
:* open the trace folder
:
=== PBX connect form===
:: [[Image:myapps-connect.png|myapps-connect.png/|myapps-connect.png/]]
: Allows the user to specify the connect data for the PBX (i.e. IP address or DNS name)
:
=== Advanced settings===
::[[Image:myapps-settings0.png|myapps-settings0.png/|myapps-settings0.png/]]
::[[Image:myapps-settings.png|myapps-settings.png/|myapps-settings.png/]] [[Image:myapps-settings2.png|myapps-settings2.png/|myapps-settings2.png/]] [[Image:myapps-settings3.png|myapps-settings3.png/|myapps-settings3.png/]]

: Allows to modify various platform dependant settings (such as e.g. the hotkey selection on Windows)

== Interfaces ==
=== Provided APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm com.innovaphone.search] : access to local phone book entries by the [[#Local phonebook access|Local phonebook access]] component.
; [http://sdk.innovaphone.com/web1/com.innovaphone.launcher/com.innovaphone.launcher.htm com.innovaphone.launcher] : display of OS specific user notifications and receipt of related user actions
; com.innovaphone.notificationhandler : reports back click on a notification.
; com.innovaphone.externalapps : to start external applications, see [[#Call an external application for calls|Call an external application for calls]] above

=== Used APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm com.innovaphone.phone] : used to initiate new or manipulate existing calls by the [[#Hot keys|Hot keys]] and [[#URL handler|URL handler]] components.

; [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm com.innovaphone.chat] : used to start a new chat by the [[#URL handler|URL handler]] component.

; [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client] : the model is used to learn the update settings, see [[#Auto update|Auto update]] above

=== Protocols ===

; [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol] : used by apps to allocate RTP channels, see [[#RTP service for audio.2C video and data|RTP service for audio, video and data]] above

== Related App Services ==

none

== Known limitations ==
; Incoming call as banner on myApps for iOS : Since iOS 14 the iOS CallKit presents incoming calls as a banner leaving the original green answer button of myApps visible. Use only the blue button of the banner to accept the call or change iPhone Settings, App "Phone", "Incoming Calls" to "Full Screen" to hide the myApps user interface again during call answering.

; Call answer in speakerphone mode even with active Bluetooth headset on myApps for iOS : This causes unwanted speakerphone operation if the smartphone is used with a Bluetooth car audio system. The behaviour can be changed by selecting ''Bluetooth Headset'' in this setting:
:''iOS Settings->Accessibility->Touch->Call Audio Routing: Automatic / Bluetooth Headset / Speaker''
:''iOS Einstellungen->Bedienungshilfen->Tippen->Anrufaudioausgabe: Automatisch / Bluetooth-Headset / Lautsprecher''

; Windows Server 2016 (Windows 10 Build 1607) : windows just shows the first notification. Further notifications aren't displayed until the previous ones are removed from the notification center. Current windows builds do not show this behaviour anymore.

; Problems on Mac computers with Yealink USB headsets
: we have received reports that myApps quits unexpectedly on some Mac computers when a Yealink headset is plugged in. Unfortunately, we could not find out the cause yet. If you use Yealink USB headsets and have a similar issue, please open a support ticket and send myApps traces.

; Poly / Plantronics headset buttons only functional if myApps is started with Rosetta
: myApps macOS supports Apple M1/M2 hardware natively. However, the Poly / Plantronics headset SDK is only available for Intel platform and thus myApps needs to be started via Apple's Intel emulator Rosetta if a Poly / Plantronics headset is used. This is done with right-click on the myApps executable, ''Information'', ''Open with Rosetta''.

; Windows surface devices may not work correctly
: Chromium does not get touch keyboard events. USB Keyboards may not be recognized either.

= Installation =

== Windows ==

myApps platform services are installed on Windows using the .msi file found in the ''myApps Windows'' package from [https://store.innovaphone.com/release/download.htm store.innovaphone.com].

myApps can update itself automatically, see [[#Auto update|Auto update]] above.

=== MSI Parameters and install options ===

The MSI installer of myApps for Windows supports the following parameters and can be edited with [https://docs.microsoft.com/en-us/windows/win32/msi/orca-exe Microsoft Orca]. You can add your parameters in the table ''property''.

; SERVER (REG_SZ): the PBX's server address (without protocol like https://)
; OFFICEPRESENCE (REG_DWORD): '''false''' to disable presence integration in Microsoft Office
: this is also available as a check-mark when running the install manually

; DISABLEHEADSETS (REG_DWORD): '''true''' to disable headsets support, see [[#Device handling|Device handling]] above

; EXTERNALAPPS (REG_SZ): pre-define external applications, see [[#Call an external application for calls|Call an external application for calls]] above
: e.g. <code>"{""externalApps"":[{""id"":0,""name"":""Wireshark"",""path"":""C:\\Program Files\\Wireshark\\Wireshark.exe"",""param"":""test $I""}]}"</code>

; FORCERESTART (REG_DWORD): '''true''' (or any string ...) kills myApps during the installation and restarts it for the currently logged in user, if it was running

; DISABLELOCALHOST (REG_DWORD): '''true''' to disable use of '''localhost''' string to access the local webserver. Use '''127.0.0.1''' instead

; EXCLUDEINTERFACES (REG_SZ): some VPN interfaces are not detected by Windows as IF_TYPE_PPP or IF_TYPE_TUNNEL and therefore the '''media outside VPN''' setting is not taking effect. With this option interfaces can be pre-defined that will not be used for media. Interfaces must be comma separated
: e.g. <code>EXCLUDEINTERFACES="172,192.168,10.10"</code>

; FASTERDOWNLOADS (REG_DWORD): '''true''' to have faster downloads without artificially slowing down the download of an update (which is done to avoid audio lags if clients have slow networks).

Current settings are stored in the registry at <code>Computer\HKEY_CURRENT_USER\Software\innovaphone\myApps</code> or at <code>Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\innovaphone\myApps</code>

Boolean values like OfficePresence are stored in registry entries with type REG_DWORD and values 1 or 0. 0 disables the setting and 1 enables it.

== iOS ==

myApps platform services are installed on iOS by loading ''innovaphone myApps'' from the ''App Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist>

== macOS ==

myApps platform services might be installed directly from the Apple store. An installer package <code>myapps.pkg</code> and a disk image <code>myapps.dmg</code> is also available from the innovaphone app store. Install <code>myapps.pkg</code> by double-click on the file and follow the instructions of the installer. myApps becomes available in the Applications folder and can be opened by double-click. Or download and open <code>myapps.dmg</code> and double klick myApps. If desired integrate it into the app dock by right click, ''Options, Keep in the dock''.

If installed from the innovaphone app store, myApps can update itself automatically, see [[#Auto update|Auto update]] above.

If installed from the Apple store, macOS notifies about updates on the Apple store. myApps [[#Auto update|Auto update]] is disabled then.

If a clean-install of the client is necessary, the folder "/Users/username/Library/Containers/myapps" needs to be deleted. To be on the safe side also delete it from the trash bin.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist>

=== Preferences ===

macOS supports preference settings that can be set via a shell command or via Mac remote management

defaults write com.innovaphone.client-ios-14r1 server "PBX-server-URL"

The following parameters and can be set through this method:

; server: the PBX's server URL

=== Setting myApps as Default App for SIP-URLs ===

{| class="wikitable"
|defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add '{
LSHandlerURLScheme = sip;
LSHandlerRoleAll = "<CFBundleIdentifier>";
}'
|}

To find the “CFBundleIdentifier”, proceed as follows:
* In the Finder under “Applications”, search for the desired myApps client that you want to set as the default app.
* Right-click on “Show package contents” -> you will find the “CFBundleIdentifier” in the Info.plist file.

A restart of the MAC is required.

=== Using Sennheiser headsets ===
If you use Sennheiser headsets, you should also install the then-current <code>DSEA_SDK_v</code>''version''<code>.pkg</code> package, after you installed the myApps client. Without that, audio will still work, but not the controls on the headset. You will need to keep that up-to-date yourself, as it is not updated by myApps's auto-update function.

== Android ==

myApps platform services are installed on Android by loading ''innovaphone myApps'' from the ''Play Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying a property "server" with string value "pbx.example.com" in the MDM.

= Configuration =

== Server configuration ==
When opening myApps for the first time, the user is prompted for the Server. Usually only the hostname (DNS host name or IP address) needs to be configured.

But there are more options for special PBX configurations.

; Non-standard HTTPS port
: If the PBX uses a non-standard HTTPS port, it must be appended to the host name separated by a colon (<code>:</code>).
: Example: <code>pbx.example.com:4444</code> (expands to <code>https://pbx.example.com:4444/PBX0/APPCLIENT/appclient.htm</code>)
; DynPBX module name
: If the PBX is a DynPBX, the module id must be appended to PBX0 separated - (<code>/</code>).
: Example: <code>pbx.example.com/PBX0-1</code> (expands to <code>https://pbx.example.com/PBX0-1/APPCLIENT/appclient.htm</code>)
; Softphone physical location
: If user defined physical location shall be used for softphone, you can append it using a parameter <code>#phys=</code>.
: Example: <code>pbx.example.com#phys=slave</code> (expands to <code>https://pbx.example.com/PBX0/APPCLIENT/appclient.htm#phys=slave</code>)

Example 1: PBX pbx.example.com with standard configuration
pbx.example.com

Example 2: PBX slave.example with DynPBX module ID 1, HTTPS port 4444 and physical location master
slave.example.com:4444/PBX0-1#phys=master

=== HTTP proxy support ===

myApps platform services do support operation via HTTP proxy now. If one or more proxies have been configured in the network settings of the operating system for the active network connection, HTTP CONNECT tunnels are established.

On Windows user name and password can be specified for the tunnel servers as generic credentials in the credentials manager (Anmeldeinformationsverwaltung). The name of the credentials must be the tunnel server hostname.

On Android user name and password can be specified through Android ''Settings, Accounts'' by adding a myApps ''HTTP Proxy Credentials'' account. The name of the account must be the tunnel server hostname.

== Platform specific settings ==
When myApps runs under the myApps platform services, it will show various platform specific settings as part of its ''burger menu'', so the user can set them. See ''Advanced settings'' in [[#UI elements|UI elements]] above.

Some options can also be set globally for all myApps clients in the PBX's [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps ''Client Settings'']]
{|
! style="text-align: left; font-weight: bold" | Option

! style="text-align: left; font-weight: bold" | Description

! style="text-align: left; font-weight: bold" | Where to set

!
! style="text-align: left; font-weight: bold"| Availability
|-

| || || User menu || PBX ''Client Settings'' || Windows || iOS || Android || macOS

|-
| Autostart || Launch myApps on login || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| Appear offline after || controls after which idle time a user is considered ''inactive''. See [[#User activity|User activity]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔
|-

| Hotkeys || Hotkeys for call dial, accept, reject. See [[#Hot keys|Hot keys]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| Docking || Docking mode (left, right, none). See [[#???|??]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✗

|-

| Desktop notifications|| Turn on/off platform notifications. See [[#Notifications| Notifications]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| VPN || Disable VPN address for ICE candidate selection. See [[#RTP ports| RTP ports]] above || ✔ ||✔ ||✔ || ✗ || ✔ || ✔

|-

| Show in taskbar|| Show myApps in the taskbar in addition to it's tray icon. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗

|-

| Log flags || turn on/off certain trace levels. See [[#Troubleshooting|Troubleshooting]] below. || ✔ ||✔ ||✔ || ✔ || ✔ || ✔

|-

| External applications || define the applications available for Apps to be started. See [[#Call an external application for calls|Call an external application for calls]] above. || ✔ ||✗ ||✔ || ✗ || ✗ || ✔

|-

| Ring in headset || send ring tone for incoming to headset instead of loudspeaker. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗
|}
== Start parameters for Windows ==

On Windows, it is not possible to pass start parameters from the [https://www.chromium.org/developers Chromium documentation] to the myApps process.

== OS Settings for Windows ==
Windows settings can influence the display of ''Desktop notifications''. See [https://support.microsoft.com/en-us/help/4028678/windows-10-change-notification-settings Change notification settings in Windows 10/11] for details.

=== Windows 11 ===

* Windows 11 has a feature "do not disturb". This hides notifications if enabled.
* Windows 11 has a feature "focus". This enables "do not disturb" and thus hides notifications too.
* Windows 11 has priority settings for notifications. Ensure that VoIP notifications for calls are allowed any maybe also include myApps as an App which is allowed to show notifications.

== OS settings for Android ==
; Events : The appearance of notifications can be controlled here.

; Call accounts : For proper incoming call signaling, the call account ''myApps'' needs to be enabled. Note that on Samsung smartphones the call account switch likely toggles back and a few tries may need to be done until it persists. Please double-check the state.

; Preferred Calling Account : Choose which calling account (myApps/SIM/..) should be used for outgoing calls initiated from within the native phone app / phone book.

; Background data, unlimited data usage : Grant background data use to enable ''myApps'' to connect to the PBX immediately on an incoming call.

; Overlaying : This setting is not needed if call account ''myApps'' has been enabled. Should there be a reason for not enabling call account ''myApps'', the permission for overlaying needs to be granted on Android 10 or higher for proper call signaling.

Note: If no SIM card is installed some Android smartphones exhibit a problem dialing from the smartphone contacts. The contacts app shows a choice ''Select SIM card for this call'' but all possible dialers are greyed out. In this case make myApps the default phone app in Android settings ''Apps, Default apps, Telephony''.

== OS settings for iOS ==
; Notifications : The appearance of notifications can be controlled in iOS ''Settings, myApps''.

== OS settings for macOS ==

; Notifications : The appearance of notifications can be controlled in macOS ''Preferences, Notifications, myApps''.

=Troubleshooting=

myApps platform services can write various traces for debugging. Trace can be turned on and off selectively in the [[#Advanced settings|Advanced settings]].

The following trace flags can be set:

(''Recommended trace options are: '''App, Browser, ICE, TURN, Signaling and Audio'''. Please do not activate other flags unless innovaphone support says otherwise'')

{|
!style="text-align: left; font-weight: bold" | Abbreviation

!style="text-align: left; font-weight: bold" |code

!style="text-align: left; font-weight: bold" | description

|-
| App||0x000000001|| logs from the App Service itself
|-
| DNS||0x000000008|| logs DNS requests and results
|-
| HTTP client||0x000000080|| http client logs
|-
| TLS||0x000000400|| TLS logs
|-
| TCP||0x000000800|| TCP logs
|-
| LDS||0x000001000|| local domain sockets
|-
| WebSocket client||0x000004000|| logs outgoing websocket connections
|-
| App WebSocket||0x000008000|| logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
|-
| UDP||0x000200000|| UDP logs
|-
| DTLS||0x000400000|| logs DTLS handshake and messages
|-
| Media||0x000800000|| logs media events
|-
| Media channel||0x001000000|| logs RTP/SCTP media connections
|-
| ICE||0x002000000|| logs ICE messages between peers
|-
| TURN||0x004000000|| logs TURN messages between peers
|-
| AppSharing||0x008000000|| logs AppSharing connection
|-
| Audio||0x010000000|| logs Audio connection and headset events
|-
| Video||0x020000000|| logs video connection and webcam events
|-
| Browser||0x040000000|| logs Chromium events
|-
| AppProxy||0x080000000|| logs requests which are proxied between the local webserver and the remote server
|-
| Webserver ||0x200000000|| enables webserver specific logs
|-
| Browser Console ||0x400000000|| logs browser console events
|-
| Signaling||0x800000000|| enables logs in the signaling module for debugging calls
|}
''code'' can be or'ed and used as value for the ''Log flags'' field in [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps/Client Settings]].

; Windows :On Windows, traces are written to the <code>%LOCALAPPDATA%\innovaphone\myApps</code> directory. If you start myApps with --log-size as parameter, you can define the maximum size of a log file (e.g. --log-size=100000000 would be 100MB for each file)

:* myApps-''date-time''.txt : main log file for the platform services

:* myAppsOutlookSearch-''date-time''.txt : log file for the Outlook phone book access

:* myAppsHookController-''date-time''.txt : log file for the hot-key interceptor (see [[#Hot keys|Hot keys]])

; :myApps update installation traces are written to the <code>%windir%\temp\</code> directory.
:* myAppsInstall.txt: MSI installation file

; :myApps update service traces are written to the <code>%ProgramData%\innovaphone\myAppsUpdateService</code> directory.
:* myAppsUpdateService-''date-time''.txt: myApps update service traces

;Android : traces can be sent by e-mail.

: also, an Android device might also be connected to a PC via an USB cable to get the traces. The files can be found in <code>Android/data/com.innovaphone.clientandroid/files</code>

; iOS : traces can be sent by e-mail.

; macOS : traces can be sent by e-mail.

: also, the files can be found in <code>~/Library/Containers/com.innovaphone.client-ios/Data/Documents/</code>. Press ''Alt+N'' followed by space to get tilde ''~''.

= Known Problems =
[[:Category:Problem myApps platform services|Known Problems]]

= Related Articles =
* [[{{NAMESPACE}}:Concept_myApps]]
* [[{{NAMESPACE}}:Concept_myApps_Redundancy|Reference14r2:Concept_myApps_Redundancy]]
* [[{{NAMESPACE}}:Concept_myApps_Office_Integration|Reference14r2:Concept_myApps_Office_Integration]]
* [[{{NAMESPACE}}:Concept_myAPPs_Search_in_local-Outlook_Contacts|Reference14r2:Concept_myAPPs_Search_in_local-Outlook_Contacts]]
* [[{{NAMESPACE}}:Call_Detail_Record_CDR_PBX|Reference14r2:Call_Detail_Record_CDR_PBX]]
* [[{{NAMESPACE}}:Concept Push Notifications for myPBX iOS and Android|Reference14r2:Concept Push Notifications for myPBX iOS and Android]]
* [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]]
* [[{{NAMESPACE}}:PBX/Config/myApps]]

[[Category:Concept myApps platform services]]

Reference15r1:Concept myApps platform services

2026-03-26T08:11:51Z

Dde: /* MSI Parameters and install options */

[[Category:Concept|myApps]]

myApps platform services provide various operating system specific services which can be used by other ''Apps'' running in the [[{{NAMESPACE}}:Concept myApps|myApps client]]. Those services typically are not available in the browser's JavaScript environment and hence must be implemented in native platform code. Therefore, the platform services are installed as native executable on the respective platform.

When myApps is started in a web browser (and hence has no access to the platform services), some Apps will use [https://en.wikipedia.org/wiki/WebRTC WebRTC] services implemented by the browser instead. For ease of reference, features available in this scenario are also described here.

On windows, the platform services also come with their own web browser in which the myApps web App will be started then. This browser is based on google's [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium] open source software.
= Applies To =

* [[{{NAMESPACE}}:Concept myApps|myApps]]
* myApps for Windows
* myApps for macOS
* myApps for iOS
* myApps for Android

* myApps Web App (WebRTC)
version 14r2

=Features=
Not all features are available or required on all platforms.
{|
! style="text-align: left; font-weight: bold" | Feature

! style="text-align: left; font-weight: bold" | Description

! style="text-align: left; font-weight: bold"| Availability
|-

| || || Windows || iOS || Android || macOS || Browser<ref>This refers to the myApps web application running in a browser with no platform services available</ref>

|-
| audio || manage local audio devices to record and playback audio conversations || ✔ || ✔ || ✔ || ✔ || ✔ (audio available but devices managed by web browser)
|-

| video || manage local displays and cameras to capture and render video live stream || ✔ || ✔ || ✔ || ✔ || ✔ (video available but devices managed by web browser)

|-

| ringer || manage local ringing device || ✔ || ✔ || ✔ || ✔ || ✔
|-

| application sharing

|-

|   presenter || share an application || ✔ || ✗ || ✔ || ✔ || ✔
|-

|   consumer || view an application shared by the peer || ✔ || ✔ || ✔ || ✔ || ✔

|-

| hot keys || capture key presses for quick invocation of phone apps (e.g. dial selected number) || ✔ || ✗ || ✗ || ✔ || ✗
|-
| tel: and sip: URI handler || intercept clicks on tel: and sip: links in web sites to invoke phone apps || ✔ || ✔ || ✔ || ✔ || ✗

|-
| user activity || set presence state according to user activity || ✔ || ✗ || ✗ || ✔ || ✔<ref>limited, see [[#User activity|User activity]] below</ref>

|-

| docking || myApps can be docked persistently to the right or left edge of your screens || ✔ || ✗ || ✗ || ✗ || ✗

|-

| multi-windowing|| Apps can be launched in separate windows|| ✔ || ✗ || ✗ || ✔ || ✗

|-

| recording|| Calls can be recorded to recording app|| ✔ || ✔ || ✔ || ✔ || ✗

|-
| notifications || ||
|-
|   display notifications || display notifications with OS standard mechanism || ✔ || ✔ || ✔ || ✔ || ✔
|-
|   push notifications || receive push notifications while myApps is not running || ✗ || ✔ || ✔ || ✔ || ✔<ref>The browser needs to be running in order to receive push notifications.</ref>
|-
|   chat and apps || display notifications for chat and other apps || ✔ || ✔ || ✔ || ✔ || ✔
|-
|   calls || display notifications for incoming calls || ✔ || ✔ || ✔ || ✔ || ✗<ref>Call notifications are only displayed locally while the phone or softphone app is started.</ref>
|-

| phone book access || access local phone book || ✔ || ✔ || ✔ || ✔ || ✗
|-
| office presence provider || maps PBX presence state to Microsoft office presence state || ✔ || ✗ || ✗ || ✗ || ✗
|-

| external application start || start arbitrary external applications for calls || ✔ || ✗ || ✗ || ✔ || ✗

|-

| app proxy|| a caching proxy that provides app persistence || ✔ || ✔ || ✔ || ✔ || ✗

|-

| auto update || automatically updates myApps platform services to the same version the PBX has || ✔ || ✔ || ✗ || ✔ || ✔<ref>The then-current web app is always loaded from the PBX upon startup and hence up-to-date by definition</ref>
|-

| three party conference || initiate 3-pty-conference using Softphone-App || ✔ || ✔ || ✔ || ✔ || ✗

|-
| exclude VPN || disable use of VPN connections for audio and appsharing || ✔ || ✔ || ✔ || ✔ || ✗

|}

<references/>

=Requirements=
* innovaphone PBX 14r2 and up

== Hardware ==
Recommended hardware requirements
* Processor: Dual-core 2Ghz or higher
* RAM: 4 Gb

== myApps for Windows ==
* Windows 10 and up
* Windows Server 2016 and later versions

=== 32 & 64 bit Windows ===
* 32 bit Windows: install the myAppsSetup32.msi from the App Store
* 64 bit Windows: install the myAppsSetup.msi from the App Store
** the 64 bit variant still installs into Program Files (x86), as the main myApps.exe is still a 32bit application
** the 64 bit variant just contains an additional 64 bit binary for the outlook search

=== Windows N editions ===

Windows N editions are missing the ''Media Feature Pack'' which is pre installed on other Windows versions.

Please install the pack from [https://www.microsoft.com/en-us/software-download/mediafeaturepack Microsoft (Windows 10 pack)] before you install myApps. The installer will check if the file <code>C:\Windows\SysWOW64\mfplat.dll</code> exist on your system.

Make sure to install the correct pack depending on your Windows version! There are different packs for Windows 10 1703, 1803, 1809 and 32bit or 64bit etc.

NB: Sometimes the myApps installation will not work even though the media pack is already installed. This is because the installer has no read access to check if the package is already installed. If the above-mentioned file exists and the installer asks to install the Windows Media Feature Pack nevertheless, you have to start the myApps install with administrative rights.

=== Terminal Server environments ===

Audio driver was removed if myApps discovers that it is running in a terminal server environment like Citrix.

The audio driver is needed for the Softphone App but the Softphone App should not use an audio driver at the server side because the audio devices are plugged locally and there would be a delay sending and receiving audio data with the server.

If a customer wants to use the Softphone App at the server side he needs to make use of the myApps Plugin for virtual desktops solution:

[[{{NAMESPACE}}:MyApps_Plugin_for_Virtual_Desktops|Reference15r1:MyApps_Plugin_for_Virtual_Desktops]]

== myApps for macOS ==
* macOS 10.13 or higher

== myApps for iOS ==
* iOS 12 or higher

== myApps for Android ==
* Android 6.0 or higher. Android 6.x may need an update of the Chrome browser.

= Licenses =
* No license needed for myApps platform services

= Overview =
myApps platform services is a native executable that is installed using the standard mechanisms on the respective operating system. It provides various advanced services which can be used by the myApps web client code as well as the Apps running in the myApps context.

Also, on Windows, the platform services come with their own, dedicated browser to run myApps in. This browser is based on [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium]. On iOS, macOS and Android, it is based upon native embedded web view facilities (such as WKWebView) instead.
== Components ==

=== RTP service for audio and appsharing ===
The RTP service provides audio and appsharing as a video stream. VoIP RTP endpoints (e.g. for softphones). It supports STUN, TURN, ICE, SRTP, DTLS. Note however that unlike WebRTC, these endpoints do not ''require'' ICE and DTLS. In other words, they can communicate also with non-compliant (i.e. older) VoIP devices.

Note that the available capabilities when not running the myApps platform services depend on the used browser's WebRTC implementation. See your browser documentation for details.

Apps can request RTP channels using the [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol]'s ''AllocChannel'' message.

===== RTP ports=====

{|

| audio || 50000 -> 50099

|-

| video (app sharing) || 50100 -> 50199

|}

The RTP service will enumerate all local interfaces and create local HOST candidates for ICE. There is an option however to disregard VPN interfaces (more precisely such interfaces with type of ''IF_TYPE_PPP'' or ''IF_TYPE_TUNNEL''). This can eliminate quality issues when RTP data is transmitted through TCP based VPN tunnels.

SRFLX and RELAY candidates are obtained using the STUN and TURN server configuration passed by the App (e.g the ''softphone'' App) as part of the ''AllocChannel'' request.
<code>{"mt":"AllocChannel","channel":"81429cba-396d-43de-8a76-ec020ba8796e","iceServers":[{"urls":"turn:myturn.domaincom:4077?transport=udp","username":"turnuser","credential":"pwd","credentialType":"password"},{"urls":"stun:mystun.domain.com:4077"}],"dn":"Foo Bar","type":"RemoteRtp","kind":"video"}</code>

===== Codecs =====

The installed myApps launchers provide codecs that can be used by softphone apps for media streams. When running in a web browser the codecs depend on the browser version and operating system. See the documentation of your browser for details.

The following codecs are supported:

{|
!style="text-align:left;width:100px;"|Codec
!style="width:100px"|Windows-Launcher
!style="width:100px"|Android
!style="width:100px"|iOS
!style="width:100px"|macOS
!style="width:100px"|Firefox (Browser)
!style="width:100px"|Chrome (Browser)
!style="width:100px"|Edge (Browser)
!style="width:100px"|Safari (Browser)
!style="width:100px"|Opera (Browser)
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Audio
|-
|G711A
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G711u
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G722
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G729
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729A
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729B
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729AB
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|[https://caniuse.com/#search=Opus OPUS-NB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|[https://caniuse.com/#search=Opus OPUS-WB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Video
|-
|[https://caniuse.com/#search=VP8 VP8]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|-
|[https://caniuse.com/#search=VP9 VP9]
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|-
|[https://caniuse.com/#search=H264 H264]
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Application Sharing
|-
|Share
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|Watch
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|}

''* small presentation only'' 
''** only for 1:1 calls, not for conferences

===== Video capture =====

The default resolution for video capture is 1920x1080 if available. Otherwise, 1280x720, 640x480, 352x288 or 320x240 will be used. The frame rate is 30 fps if available, otherwise 15 fps. The resulting average bandwidth could reach 1 Mbps.

===== Application sharing =====

Screen content will be transmitted as video stream by the presenter

===== Device handling =====

The RTP service enumerates microphones, loudspeaker, cameras and ringing devices and notifies apps when devices come and go. It is up to the apps using the devices to store preferences.

The RTP service also enables some extended features (such as hook switch or volume control) for supported USB headsets or Bluetooth headsets connected to myApps.
The supported headset-SDKs determine which headset vendors are recommended to be used with the myApps softphone app. 

For this to work, the following vendor specific development kits are integrated in our myApps client. Be aware that the SDK are updated within our Service release :

{| class="wikitable"
|-
! SDK Vendor !! Supported OS !! SDK Version !! innovaphone Service Release
|-
| Jabra|| MacOS || 1.12.2.0 || 13r3sr9
|-
||| Windows || 1.12.2.0 || 13r3sr10
|-
| Epos ''(formerly Sennheiser)'' || MacOS || 12.4.0.5478 || 14r1sr3
|-
||| Windows || n.a. - [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|to be installed separately]]|| 13r3sr10
|-
| Poly ''(formerly Plantronics)'' || MacOS || 3.25.53799.37131 || 13r3sr9
|-
||| Windows || 3.25.53800.37131 || 13r3sr10
|-
| Yealink || MacOS || 3.1.1.20 || 14r1sr3
|-
||| Windows || 3.1.1.20 || 14r1sr3
|}

Notes:
* It is possible to inhibit the start of the Sennheiser SDK (SenncomSDK.exe) using the <code>DISABLEHEADSETS</code> directive of the installer (see [[#MSI Parameters and install options| MSI parameters]] below).

* Starting with V13r3sr10, the Epos-SDK needs to be installed separately using the Epos Connect software to ensure full compatibility between current Epos headset models and native myApps-Windows client. For details [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|refer to this article]].


===== Ring tones =====

Ring tones can be played. Apps can choose the tone from a pre-defined list of ring tones.

On Windows, custom ring tones can be uploaded as .mp3 files to the <code>ringtones</code> sub-directory of myApps' roaming directory (which usually is in <code>%appdata%\innovaphone\myApps\ringtones</code>).

On Android, custom ring tones can be added to the system via Android settings.

On iOS, custom ring tones can be uploaded as .mp3 files to the <code>Ringtones</code> subdirectory of the myApps file share that is available in iTunes if the iPhone has been connected via USB.

On macOS, custom ring tones can be uploaded as .mp3 files to <code>~/Library/Containers/com.innovaphone.client-macos/Data/Documents/Ringtones</code>.

===== Debugging =====
For extended debugging, turn on the ''Audio'', ''Media'' and ''AppSharing'' traces in myApps.

=== Hot keys ===
On Windows and macOS systems, myApps platform services can listen for hot keys and invoke certain functions. Invocation is done by sending API messages to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

The hot keys can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below. Any of the function keys F1 to F11 (optionally combined with up to two modifier keys ''alt'', ''ctrl'', ''shift'' or ''win'') can be chosen for each function. If you do not want to start the call with "Hotkey+Enter" because you would have to wait for the focus, the hotkey can also be pressed twice and the number is dialled directly.

; dial selected number : Initiates a call using the currently selected text as target.

: A ''PrepareCall'' message with the ''text'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":"mt":"PrepareCall","text":"13","adjust":true}}</code>

; accept call : Accepts a currently alerting call.

: A ''ConnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"ConnectCall"}}</code>

; reject/disconnect call : Rejects a currently alerting call or disconnects an active call.

: A ''DisconnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"DisconnectCall"}}</code>

=== URL Handler ===

On Windows systems, two URI-handler are installed with the myApps platform services. Windows will call up this URI handler when a user clicks on an appropriate link, for example in a web site.

The handler will the send an API message to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

; tel URI : call a number, e.g. <code>tel:4711</code>

: A ''PrepareCall'' message with the ''num'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","num":"4711","adjust":true}}</code>
; sip URI : call a SIP name, e.g. <code>sip:zkl@innovaphone.com</code>

: A ''PrepareCall'' message with the ''sip'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","sip":"zkl@innovaphone.com","adjust":true}}</code>
; im URI : start chat with SIP name, e.g. <code>im:zkl@innovaphone.com</code>

: A ''StartChat'' message with the ''sip'' argument set to the selected text will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm ''com.innovaphone.chat'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.chat","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartChat","sip":"zkl@innovaphone.com"}}</code>

On macOS systems myApps might be made the default application to handle tel URI e.g. <code>tel:4711</code> via Apple FaceTime. Open the "FaceTime" menu "Settings..." and select myApps as "Default for phone calls".

On iOS ''tel'' URIs are always dialed via GSM. Therefore myApps iOS also reacts to URI schemes ''com.innovaphone.tel'', ''com.innovaphone.sip'' and ''com.innovaphone.im'', e.g. <code><nowiki>com.innovaphone.tel:4711</nowiki></code>, <code><nowiki>com.innovaphone.sip:zkl@innovaphone.com</nowiki></code>, <code><nowiki>com.innovaphone.im:zkl@innovaphone.com</nowiki></code>.

=== User activity ===
On Windows and macOS systems, the myApps platform services can monitor user keyboard/mouse activity and change the user's presence state after a certain amount of inactivity. The timeout can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below.

myApps will then send a [https://sdk.innovaphone.com/doc/appwebsocket/myApps.htm#SetUserActivity''SetUserActivity''] message to the PBX using the ''myApps'' protocol.

: <code>{"mt":"SetUserActivity","inactive":true}</code>

This will change the ''status'' property of the ''im:'' contact for the user's own presence and hence result in a presence update from the PBX to myApps

: <code>{"mt":"UpdateOwnPresence","presence":[{...},{"contact":"im:","activity":"","status":"closed"}]}</code>
The ''closed'' status is reflected in the grey status color when displaying a contact [[Image:myapps-inactive.png|myapps-inactive.png/|myapps-inactive.png/]].

On iOS and Android, the state is set to ''inactive'' as soon as the App is brought to background.
When myApps platform services are not available (i.e. when running the web application in a browser solely) a limited user activity monitoring is available: the state is set to active when the web page is not used for more than 5 minutes.

=== Recording ===

The new launcher offers the possibility to record the audio of incoming and outgoing calls. In order to activate that functionality the URL of the recording instance must be configured in either the PBX (PBX->myApps->Config: Recording URL) or the softphone App (Settings->Audio Recording (URL))

[[Image:PBX-Recording-Settings.png|pbx-recording-settings.png/|pbx-recording-settings.png/]] [[Image:Recording-Softphone-Settings.png|recording-softphone-settings.png/|recording-softphone-settings.png/]].

As long as that URL is configured the audio data of all calls are stored as pcap-files under that URL.
If the URL points to a CF device in the PBX, write access must be granted for that URL (PBX->Services->HTTP->Server:Public compact flash access) and if the URL points to the recording app, the files can be accessed via the recording app [[{{NAMESPACE}}:Concept_App_Service_Recordings|recording]].

Under PBX->myApps the administrator can set a certain default behaviour of the audio recording like whether or not the recording should start automatically at the beginning of the call (Recording by Default ON/OFF), only calls with external numbers should be recorded (Record external calls only) or whether or not the user should be able to start/stop the recording himself (Allow user incall recording control). Except for the last parameter these parameters can also be modified by the user in its softphone settings if the administrator doesn't set the FORCE flag.

If the user was allowed by the admin to control the recording a recording switch is active during the call when the "Media" Panel is opened. There the audio recording may be stopped and continued at will. A red recording notice is shown in the top right corner when the recording actually takes place.

[[Image:Recording-incall-switch.png|recording-incall-switch.png/|recording-incall-switch.png/]]

=== Notifications ===

The myApps platform services can use the OS specific notification mechanism (e.g. ''desktop notifications'' on Windows) to display messages (e.g. ''incoming new chat message'') to the user.

Note that the actual rendering of the notification is under control of the OS. Therefore, myApps must be allowed to show notifications and its appearance can be restricted by OS native settings.

==== Microsoft Windows Notifications ====

Microsoft Windows Server editions (2016, 2019, 2022) are just capable of showing a single ''IncomingCall'' notification at the same time (we couldn't find a workaround for this limitation). 
An ''IncomingCall'' notification is visible the whole time instead of being moved to the action center after a certain time. 
 
A notification about a missed call uses the ''IncomingCall'' type so that this notification is visible until the user returns. 
Due to the above limitation, on a new arriving call such a missed call notification is transformed to a default notification which will be moved to the action center automatically. 
 
On non server editions, you can have multiple IncomingCall notifications at the same time (so two parallel incoming calls will be indeed notified at the same time), but the missed call notification handling is the same on both platforms!

Thus there will be always just '''one''' missed call notification visible and previous missed calls can be found inside your action center!

To see myApps notifications, ensure:
* System -> Notifications
** enable notifications
** disable "Do not disturb" or allow myApps as priority application while "Do not disturb" is active
** enable notifications for myApps in the list of applications
* System -> Focus
** if a focus session is active and the "Do not disturb" is activated during a focus session, make sure that myApps is a priority application (see above)

==== macOS Notifications ====
Notifications are the same as on Windows.
The difference is, that for macOS, notifications need to be allowed in the system settings.
Go to Notifications - myApps, select Banner and enable all check marks.

=== Local phonebook access ===
'''Contact Search:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm ''com.innovaphone.search'' API]]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Search'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{"mt":"Search","type":"contact","search":"john doe"},"apiId":"com.innovaphone.search"}</code>
Search results are delivered as ''SearchInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{"mt":"SearchInfo","relevance":2000,"adjust":true,"type":"contact","contact":{"givenname":"John","sn":"Doe","company":"ACME","position":"Head of everything","telephonenumber":["11111","22222"],"homephone":["+4944444","33333"],"mobile":["+49 (123) 55555"]}},"api":"com.innovaphone.search"}</code>

'''Reverse Lookup:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.phonelookup/lib1_api_phonelookup.htm ''com.innovaphone.phonelookup'' API]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Lookup'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{ mt: "Lookup", prefixIntl: "000", prefixNtl: "00", prefixExt:"0", area: "7031", country: "49", lookup: "0004970311234567" },"apiId":"com.innovaphone.lookup"}</code>

Search results are delivered as ''LookupInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{mt: "LookupInfo", dn: "Jake Blues", contact: { telephonenumber: ["0004970311234567"], givenname: "Jake", sn: "Blues", company: "Blues Brothers" </code>

==== Windows ====
On Windows, the search and lookup are performed in all of the user's Outlook contact folders. As opposed to the search implemented in the ''Contacts'' and ''Users'' App, all items are returned which match any of the search words (i.e. searching for ''a b'' will return items matching either ''a'' or ''b'').

; searched properties : firstname, lastname
; returned properties : Following Outlook contact phone number properties are returned (if available):

:* OFFICE_TELEPHONE_NUMBER as ''telephonenumber''
:* OFFICE2_TELEPHONE_NUMBER as ''telephonenumber''
:* HOME_TELEPHONE_NUMBER as ''homephone''
:* HOME2_TELEPHONE_NUMBER as ''homephone''
:* MOBILE_TELEPHONE_NUMBER as ''mobile''
:* BUSINESS_FAX_NUMBER as ''facsimiletelephonenumber''
Note that contact information is cached in the search provider. Updated contacts may therefore become effective after a while only.
Outlook search will create its own trace file <code>myAppsOutlookSearch-</code>''date-time''<code>.txt</code> in the standard trace directory.

This search provider is always installed and can be disabled. There is no need (nor possibility) to enable it in the ''Apps'' tab of the PBX's user object. Also, no ''App'' object needs to be created for it.

==== Android/iOS ====
The search and lookup are performed in the contacts.

==== macOS ====
The search and lookup are performed in the contacts. If you wish to disable local contact lookup, go to system settings - Security & Privacy and disable the access to contacts for myapps.

=== Microsoft Office integration ===

The myApps platform services has a ''office presence provider'' that can provide the user's presence state to Office applications. See [[{{NAMESPACE}}:Concept_myApps_Office_Integration|myApps Office Integration]] for details.

This feature is installed by default. However, it can be disabled using the ''OFFICEPRESENCE'' MSI Parameter. Also, a check-mark is available in the setup dialog.

=== Call an external application for calls ===

Phone Apps (such as the phoneapp or softphone) can initiate the start of an external application when a new call appears (either incoming or outgoing). The actual spawning of the application is done by the myApps platform service. Also, the application properties (such as e.g. the executable's path) is configured in the myApps platform services (see [[#UI elements|Advanced settings]] in the ''UI elements'' section below).

A number of arguments can be passed to the application by substituting $-variables in the ''Parameter'' field:

; $n : phone number as dialed (called party number for outgoing calls) or received (calling party number for incoming calls)

; $N : called or calling party number in ''national'' format (e.g. 07031730090)

; $I : called or calling party number in ''international'' format (e.g. +497031730090)

: note that both $N and $I only work if $n includes both subscriber number and area code (e.g. 07031730090). Otherwise they are equal to $n

; $d : display name of peer (if known)

; $u : URI name of the peer (if available eg with a federation call)

; $c : conference id

: this is a globally unique ID for this call and may be used to relate the call to the ''guid'' found in the CallInfo structure in the [http://wiki.innovaphone.com/index.php?title=Reference10:SOAP_API#CallInfo SOAP-API] and [http://sdk.innovaphone.com/doc/appwebsocket/RCC.htm RCC-API ]. Also, corresponding [[Reference10:Call Detail Record CDR PBX|CDRs]] can be related using the ''event'' tag's ''conf'' attribute.
The start of an external application can be requested using the ''com.innovaphone.externalapps'' API.

Some setup examples are [[Howto:Integrate External Apps in innovaphone UC clients|shown here]].

=== Push ===

Mobile operating systems usually inhibit network operation of apps which run in the background or are closed by the user. This is done in order to reduce battery consumption. Unfortunately, this also stops such apps to maintain a registration by regularly sending ''keep alive'' messages to a server (in our case to the PBX). As a result, myApps will be disconnected from the PBX. When the PBX determines that there is an event for the application which needs a response, it needs to wake up the app using a dedicated channel provided by the operating system. This mechanism is know as ''push''. When running on iOS or Android, myApps supports ''push''.

For ''push'' to work, a [[{{NAMESPACE}}:PBX/Objects/Push|''push object'']] needs to be configured in the PBX . Also, it needs to be enabled on the mobile phone for the myApps app.
This mechanism is quite similar in v12 and v13, so you can refer to [[{{NAMESPACE}}:Concept_Push_Notifications_for_iOS_and_Android|Reference14r2:Concept_Push_Notifications_for_iOS_and_Android]] for more details.

Also, helpful hints can be found in [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]].

=== App Proxy ===

myApps runs further ''Apps'' (such as e.g. the ''phoneapp'') as a web page in an IFRAME of the browser myApps is running in. The App's page code is loaded either from the PBX or from an ''application platform'' (AP). This however would mean that the App's IFRAME would remain empty (a dead white screen) when the PBX or AP is not available. To make sure the App can start-up anyway, the myApps platform services feature the so-called ''App Proxy''. This is a caching proxy that caches all the App code so it is available even in case of network failure. When myApps runs in the context of the platform services, Apps are therefore not loaded from the App source directly, but from the local App proxy.

The cached files are stored in the PCs local file system in the <code>%LOCALAPPDATA%\innovaphone\myApps\appproxy</path></code>. There is no configuration required. However, if myApps seems to run with outdated or corrupt cached copies of the App, you can safely delete the entire directory.

=== Auto update ===

On Windows and on macOS, the myApps platform services can auto-update themselves to a common version. This is controlled by the [[{{NAMESPACE}}:PBX/Config/myApps#Launcher_Software_Update | ''Launcher Software Update'']] settings under ''PBX/Config/myApps'' in the PBX.

When myApps is started or the user logs in or myApps needs to re-connect to the PBX, the platform services will use the [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client API] to learn the desired version (''launcherUpdateBuild'', which is part of the API's ''model''). If this differs from the current version, the platform services will try to download the respective new version.

{
"mt": "ApiUpdate",
"apis": {
"com.innovaphone.client": {
"@client": {
"title": "innovaphone myApps",
"model": {
"launcher": true,
"launcherUpdateBuild": "134906",
"appStoreUrl": "http://store.innovaphone.com/release/download/"
}
}
}
}
}

The installation of the downloaded version is done by the ''innovaphonemyAppsUpdateService''. This service is installed and enabled during the initial installation of the myApps platform services. To disable auto-update, either leave the ''Launcher Software Update'' settings empty or set the service's start mode to ''disabled'' in the Windows ''services control panel''.

Note that on Windows the update service does not work on terminal servers. Administrators must do myApps base services updates using standard windows mechanisms.

Note that on macOS if myApps has been installed from the Apple Store it is assumed that auto update from the PBX is not desired and disabled therefore.

On Android/iOS/macOS updates can be downloaded from the respective app store.

The ''Devices'' app can not update software installed on Windows PCs directly. However, when the PBX is updated using an ''update job'' in the ''Devices'' App, the ''Launcher Software Update'' settings will be updated accordingly and hence the myApps base services will ultimately also be updated to the same version.

==== Auto update flow on Windows ====

* On start of myApps, myApps checks if an update is available and ready for installation
** if yes, the update is installed directly, without user interaction (a popup is shown during the installation)
** if not, myApps starts
* if an update is available while myApps is already running, an update notification will be shown which let's the user choose to install the update now or later (the notification will then popup again after one hour)

==UI elements ==
There are a few user interfaces provided by the platform services:
===tray-icon (Windows only) ===
::[[Image:myapps-tray.png|myapps-tray.png/|myapps-tray.png/]]
:Allows to
:* terminate myApps
:* toggle the ''autostart'' state
:* toggle the ''show in task bar'' state
:* open the trace folder
:
=== PBX connect form===
:: [[Image:myapps-connect.png|myapps-connect.png/|myapps-connect.png/]]
: Allows the user to specify the connect data for the PBX (i.e. IP address or DNS name)
:
=== Advanced settings===
::[[Image:myapps-settings0.png|myapps-settings0.png/|myapps-settings0.png/]]
::[[Image:myapps-settings.png|myapps-settings.png/|myapps-settings.png/]] [[Image:myapps-settings2.png|myapps-settings2.png/|myapps-settings2.png/]] [[Image:myapps-settings3.png|myapps-settings3.png/|myapps-settings3.png/]]

: Allows to modify various platform dependant settings (such as e.g. the hotkey selection on Windows)

== Interfaces ==
=== Provided APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm com.innovaphone.search] : access to local phone book entries by the [[#Local phonebook access|Local phonebook access]] component.
; [http://sdk.innovaphone.com/web1/com.innovaphone.launcher/com.innovaphone.launcher.htm com.innovaphone.launcher] : display of OS specific user notifications and receipt of related user actions
; com.innovaphone.notificationhandler : reports back click on a notification.
; com.innovaphone.externalapps : to start external applications, see [[#Call an external application for calls|Call an external application for calls]] above

=== Used APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm com.innovaphone.phone] : used to initiate new or manipulate existing calls by the [[#Hot keys|Hot keys]] and [[#URL handler|URL handler]] components.

; [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm com.innovaphone.chat] : used to start a new chat by the [[#URL handler|URL handler]] component.

; [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client] : the model is used to learn the update settings, see [[#Auto update|Auto update]] above

=== Protocols ===

; [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol] : used by apps to allocate RTP channels, see [[#RTP service for audio.2C video and data|RTP service for audio, video and data]] above

== Related App Services ==

none

== Known limitations ==
; Incoming call as banner on myApps for iOS : Since iOS 14 the iOS CallKit presents incoming calls as a banner leaving the original green answer button of myApps visible. Use only the blue button of the banner to accept the call or change iPhone Settings, App "Phone", "Incoming Calls" to "Full Screen" to hide the myApps user interface again during call answering.

; Call answer in speakerphone mode even with active Bluetooth headset on myApps for iOS : This causes unwanted speakerphone operation if the smartphone is used with a Bluetooth car audio system. The behaviour can be changed by selecting ''Bluetooth Headset'' in this setting:
:''iOS Settings->Accessibility->Touch->Call Audio Routing: Automatic / Bluetooth Headset / Speaker''
:''iOS Einstellungen->Bedienungshilfen->Tippen->Anrufaudioausgabe: Automatisch / Bluetooth-Headset / Lautsprecher''

; Windows Server 2016 (Windows 10 Build 1607) : windows just shows the first notification. Further notifications aren't displayed until the previous ones are removed from the notification center. Current windows builds do not show this behaviour anymore.

; Problems on Mac computers with Yealink USB headsets
: we have received reports that myApps quits unexpectedly on some Mac computers when a Yealink headset is plugged in. Unfortunately, we could not find out the cause yet. If you use Yealink USB headsets and have a similar issue, please open a support ticket and send myApps traces.

; Poly / Plantronics headset buttons only functional if myApps is started with Rosetta
: myApps macOS supports Apple M1/M2 hardware natively. However, the Poly / Plantronics headset SDK is only available for Intel platform and thus myApps needs to be started via Apple's Intel emulator Rosetta if a Poly / Plantronics headset is used. This is done with right-click on the myApps executable, ''Information'', ''Open with Rosetta''.

; Windows surface devices may not work correctly
: Chromium does not get touch keyboard events. USB Keyboards may not be recognized either.

= Installation =

== Windows ==

myApps platform services are installed on Windows using the .msi file found in the ''myApps Windows'' package from [https://store.innovaphone.com/release/download.htm store.innovaphone.com].

myApps can update itself automatically, see [[#Auto update|Auto update]] above.

=== MSI Parameters and install options ===

The MSI installer of myApps for Windows supports the following parameters and can be edited with [https://docs.microsoft.com/en-us/windows/win32/msi/orca-exe Microsoft Orca]. You can add your parameters in the table ''property''.

; SERVER (REG_SZ): the PBX's server address (without protocol like https://)
; OFFICEPRESENCE (REG_DWORD): '''false''' to disable presence integration in Microsoft Office
: this is also available as a check-mark when running the install manually

; DISABLEHEADSETS (REG_DWORD): '''true''' to disable headsets support, see [[#Device handling|Device handling]] above

; EXTERNALAPPS (REG_SZ): pre-define external applications, see [[#Call an external application for calls|Call an external application for calls]] above
: e.g. <code>"{""externalApps"":[{""id"":0,""name"":""Wireshark"",""path"":""C:\\Program Files\\Wireshark\\Wireshark.exe"",""param"":""test $I""}]}"</code>

; FORCERESTART (REG_DWORD): '''true''' (or any string ...) kills myApps during the installation and restarts it for the currently logged in user, if it was running

; DISABLELOCALHOST (REG_DWORD): '''true''' to disable use of '''localhost''' string to access the local webserver. Use '''127.0.0.1''' instead

; EXCLUDEINTERFACES (REG_SZ): some VPN interfaces are not detected by Windows as IF_TYPE_PPP or IF_TYPE_TUNNEL and therefore the '''media outside VPN''' setting is not taking effect. With this option interfaces can be pre-defined that will not be used for media. Interfaces must be comma separated
: e.g. <code>EXCLUDEINTERFACES="172,192.168,10.10"</code>

; FASTERDOWNLOADS (REG_DWORD): '''1''' to have faster downloads without artificially slowing down the download of an update (which is done to avoid audio lags if clients have slow networks).

Current settings are stored in the registry at <code>Computer\HKEY_CURRENT_USER\Software\innovaphone\myApps</code> or at <code>Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\innovaphone\myApps</code>

Boolean values like OfficePresence are stored in registry entries with type REG_DWORD and values 1 or 0. 0 disables the setting and 1 enables it.

== iOS ==

myApps platform services are installed on iOS by loading ''innovaphone myApps'' from the ''App Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist>

== macOS ==

myApps platform services might be installed directly from the Apple store. An installer package <code>myapps.pkg</code> and a disk image <code>myapps.dmg</code> is also available from the innovaphone app store. Install <code>myapps.pkg</code> by double-click on the file and follow the instructions of the installer. myApps becomes available in the Applications folder and can be opened by double-click. Or download and open <code>myapps.dmg</code> and double klick myApps. If desired integrate it into the app dock by right click, ''Options, Keep in the dock''.

If installed from the innovaphone app store, myApps can update itself automatically, see [[#Auto update|Auto update]] above.

If installed from the Apple store, macOS notifies about updates on the Apple store. myApps [[#Auto update|Auto update]] is disabled then.

If a clean-install of the client is necessary, the folder "/Users/username/Library/Containers/myapps" needs to be deleted. To be on the safe side also delete it from the trash bin.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist>

=== Preferences ===

macOS supports preference settings that can be set via a shell command or via Mac remote management

defaults write com.innovaphone.client-ios-14r1 server "PBX-server-URL"

The following parameters and can be set through this method:

; server: the PBX's server URL

=== Setting myApps as Default App for SIP-URLs ===

{| class="wikitable"
|defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add '{
LSHandlerURLScheme = sip;
LSHandlerRoleAll = "<CFBundleIdentifier>";
}'
|}

To find the “CFBundleIdentifier”, proceed as follows:
* In the Finder under “Applications”, search for the desired myApps client that you want to set as the default app.
* Right-click on “Show package contents” -> you will find the “CFBundleIdentifier” in the Info.plist file.

A restart of the MAC is required.

=== Using Sennheiser headsets ===
If you use Sennheiser headsets, you should also install the then-current <code>DSEA_SDK_v</code>''version''<code>.pkg</code> package, after you installed the myApps client. Without that, audio will still work, but not the controls on the headset. You will need to keep that up-to-date yourself, as it is not updated by myApps's auto-update function.

== Android ==

myApps platform services are installed on Android by loading ''innovaphone myApps'' from the ''Play Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying a property "server" with string value "pbx.example.com" in the MDM.

= Configuration =

== Server configuration ==
When opening myApps for the first time, the user is prompted for the Server. Usually only the hostname (DNS host name or IP address) needs to be configured.

But there are more options for special PBX configurations.

; Non-standard HTTPS port
: If the PBX uses a non-standard HTTPS port, it must be appended to the host name separated by a colon (<code>:</code>).
: Example: <code>pbx.example.com:4444</code> (expands to <code>https://pbx.example.com:4444/PBX0/APPCLIENT/appclient.htm</code>)
; DynPBX module name
: If the PBX is a DynPBX, the module id must be appended to PBX0 separated - (<code>/</code>).
: Example: <code>pbx.example.com/PBX0-1</code> (expands to <code>https://pbx.example.com/PBX0-1/APPCLIENT/appclient.htm</code>)
; Softphone physical location
: If user defined physical location shall be used for softphone, you can append it using a parameter <code>#phys=</code>.
: Example: <code>pbx.example.com#phys=slave</code> (expands to <code>https://pbx.example.com/PBX0/APPCLIENT/appclient.htm#phys=slave</code>)

Example 1: PBX pbx.example.com with standard configuration
pbx.example.com

Example 2: PBX slave.example with DynPBX module ID 1, HTTPS port 4444 and physical location master
slave.example.com:4444/PBX0-1#phys=master

=== HTTP proxy support ===

myApps platform services do support operation via HTTP proxy now. If one or more proxies have been configured in the network settings of the operating system for the active network connection, HTTP CONNECT tunnels are established.

On Windows user name and password can be specified for the tunnel servers as generic credentials in the credentials manager (Anmeldeinformationsverwaltung). The name of the credentials must be the tunnel server hostname.

On Android user name and password can be specified through Android ''Settings, Accounts'' by adding a myApps ''HTTP Proxy Credentials'' account. The name of the account must be the tunnel server hostname.

== Platform specific settings ==
When myApps runs under the myApps platform services, it will show various platform specific settings as part of its ''burger menu'', so the user can set them. See ''Advanced settings'' in [[#UI elements|UI elements]] above.

Some options can also be set globally for all myApps clients in the PBX's [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps ''Client Settings'']]
{|
! style="text-align: left; font-weight: bold" | Option

! style="text-align: left; font-weight: bold" | Description

! style="text-align: left; font-weight: bold" | Where to set

!
! style="text-align: left; font-weight: bold"| Availability
|-

| || || User menu || PBX ''Client Settings'' || Windows || iOS || Android || macOS

|-
| Autostart || Launch myApps on login || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| Appear offline after || controls after which idle time a user is considered ''inactive''. See [[#User activity|User activity]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔
|-

| Hotkeys || Hotkeys for call dial, accept, reject. See [[#Hot keys|Hot keys]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| Docking || Docking mode (left, right, none). See [[#???|??]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✗

|-

| Desktop notifications|| Turn on/off platform notifications. See [[#Notifications| Notifications]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| VPN || Disable VPN address for ICE candidate selection. See [[#RTP ports| RTP ports]] above || ✔ ||✔ ||✔ || ✗ || ✔ || ✔

|-

| Show in taskbar|| Show myApps in the taskbar in addition to it's tray icon. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗

|-

| Log flags || turn on/off certain trace levels. See [[#Troubleshooting|Troubleshooting]] below. || ✔ ||✔ ||✔ || ✔ || ✔ || ✔

|-

| External applications || define the applications available for Apps to be started. See [[#Call an external application for calls|Call an external application for calls]] above. || ✔ ||✗ ||✔ || ✗ || ✗ || ✔

|-

| Ring in headset || send ring tone for incoming to headset instead of loudspeaker. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗
|}
== Start parameters for Windows ==

On Windows, it is not possible to pass start parameters from the [https://www.chromium.org/developers Chromium documentation] to the myApps process.

== OS Settings for Windows ==
Windows settings can influence the display of ''Desktop notifications''. See [https://support.microsoft.com/en-us/help/4028678/windows-10-change-notification-settings Change notification settings in Windows 10/11] for details.

=== Windows 11 ===

* Windows 11 has a feature "do not disturb". This hides notifications if enabled.
* Windows 11 has a feature "focus". This enables "do not disturb" and thus hides notifications too.
* Windows 11 has priority settings for notifications. Ensure that VoIP notifications for calls are allowed any maybe also include myApps as an App which is allowed to show notifications.

== OS settings for Android ==
; Events : The appearance of notifications can be controlled here.

; Call accounts : For proper incoming call signaling, the call account ''myApps'' needs to be enabled. Note that on Samsung smartphones the call account switch likely toggles back and a few tries may need to be done until it persists. Please double-check the state.

; Preferred Calling Account : Choose which calling account (myApps/SIM/..) should be used for outgoing calls initiated from within the native phone app / phone book.

; Background data, unlimited data usage : Grant background data use to enable ''myApps'' to connect to the PBX immediately on an incoming call.

; Overlaying : This setting is not needed if call account ''myApps'' has been enabled. Should there be a reason for not enabling call account ''myApps'', the permission for overlaying needs to be granted on Android 10 or higher for proper call signaling.

Note: If no SIM card is installed some Android smartphones exhibit a problem dialing from the smartphone contacts. The contacts app shows a choice ''Select SIM card for this call'' but all possible dialers are greyed out. In this case make myApps the default phone app in Android settings ''Apps, Default apps, Telephony''.

== OS settings for iOS ==
; Notifications : The appearance of notifications can be controlled in iOS ''Settings, myApps''.

== OS settings for macOS ==

; Notifications : The appearance of notifications can be controlled in macOS ''Preferences, Notifications, myApps''.

=Troubleshooting=

myApps platform services can write various traces for debugging. Trace can be turned on and off selectively in the [[#Advanced settings|Advanced settings]].

The following trace flags can be set:

(''Recommended trace options are: '''App, Browser, ICE, TURN, Signaling and Audio'''. Please do not activate other flags unless innovaphone support says otherwise'')

{|
!style="text-align: left; font-weight: bold" | Abbreviation

!style="text-align: left; font-weight: bold" |code

!style="text-align: left; font-weight: bold" | description

|-
| App||0x000000001|| logs from the App Service itself
|-
| DNS||0x000000008|| logs DNS requests and results
|-
| HTTP client||0x000000080|| http client logs
|-
| TLS||0x000000400|| TLS logs
|-
| TCP||0x000000800|| TCP logs
|-
| LDS||0x000001000|| local domain sockets
|-
| WebSocket client||0x000004000|| logs outgoing websocket connections
|-
| App WebSocket||0x000008000|| logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
|-
| UDP||0x000200000|| UDP logs
|-
| DTLS||0x000400000|| logs DTLS handshake and messages
|-
| Media||0x000800000|| logs media events
|-
| Media channel||0x001000000|| logs RTP/SCTP media connections
|-
| ICE||0x002000000|| logs ICE messages between peers
|-
| TURN||0x004000000|| logs TURN messages between peers
|-
| AppSharing||0x008000000|| logs AppSharing connection
|-
| Audio||0x010000000|| logs Audio connection and headset events
|-
| Video||0x020000000|| logs video connection and webcam events
|-
| Browser||0x040000000|| logs Chromium events
|-
| AppProxy||0x080000000|| logs requests which are proxied between the local webserver and the remote server
|-
| Webserver ||0x200000000|| enables webserver specific logs
|-
| Browser Console ||0x400000000|| logs browser console events
|-
| Signaling||0x800000000|| enables logs in the signaling module for debugging calls
|}
''code'' can be or'ed and used as value for the ''Log flags'' field in [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps/Client Settings]].

; Windows :On Windows, traces are written to the <code>%LOCALAPPDATA%\innovaphone\myApps</code> directory. If you start myApps with --log-size as parameter, you can define the maximum size of a log file (e.g. --log-size=100000000 would be 100MB for each file)

:* myApps-''date-time''.txt : main log file for the platform services

:* myAppsOutlookSearch-''date-time''.txt : log file for the Outlook phone book access

:* myAppsHookController-''date-time''.txt : log file for the hot-key interceptor (see [[#Hot keys|Hot keys]])

; :myApps update installation traces are written to the <code>%windir%\temp\</code> directory.
:* myAppsInstall.txt: MSI installation file

; :myApps update service traces are written to the <code>%ProgramData%\innovaphone\myAppsUpdateService</code> directory.
:* myAppsUpdateService-''date-time''.txt: myApps update service traces

;Android : traces can be sent by e-mail.

: also, an Android device might also be connected to a PC via an USB cable to get the traces. The files can be found in <code>Android/data/com.innovaphone.clientandroid/files</code>

; iOS : traces can be sent by e-mail.

; macOS : traces can be sent by e-mail.

: also, the files can be found in <code>~/Library/Containers/com.innovaphone.client-ios/Data/Documents/</code>. Press ''Alt+N'' followed by space to get tilde ''~''.

= Known Problems =
[[:Category:Problem myApps platform services|Known Problems]]

= Related Articles =
* [[{{NAMESPACE}}:Concept_myApps]]
* [[{{NAMESPACE}}:Concept_myApps_Redundancy|Reference14r2:Concept_myApps_Redundancy]]
* [[{{NAMESPACE}}:Concept_myApps_Office_Integration|Reference14r2:Concept_myApps_Office_Integration]]
* [[{{NAMESPACE}}:Concept_myAPPs_Search_in_local-Outlook_Contacts|Reference14r2:Concept_myAPPs_Search_in_local-Outlook_Contacts]]
* [[{{NAMESPACE}}:Call_Detail_Record_CDR_PBX|Reference14r2:Call_Detail_Record_CDR_PBX]]
* [[{{NAMESPACE}}:Concept Push Notifications for myPBX iOS and Android|Reference14r2:Concept Push Notifications for myPBX iOS and Android]]
* [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]]
* [[{{NAMESPACE}}:PBX/Config/myApps]]

[[Category:Concept myApps platform services]]

Reference16r1:Concept innovaphone App Platform Container

2026-03-24T13:47:29Z

Dde:

{{FIXME|reason=Below described feature is experimental and not officially supported for use in productive environments.}}
The innovaphone App Platform Container provides a myApps App Platform instance that includes the AP Manager, Webserver and PostgreSQL. This container offers a ready-to-use environment for myApps applications and the innovaphone PBX.

== Applies To ==

* innovaphone App Platform Container

==Requirements==
* Host with docker on a x86_64 (amd64) platform
* innovaphone App Platform Container

==Concept==

The innovaphone App Platform Container provides the innovaphone App Platform for container environments (Open Container Initiative (OCI) format).

* The App Platform Manager and Webserver Apps are already integrated in the container and provide the already known functionality.
* Apps are installed, updated and managed as usual.
* The mount point will be used for the database, the App binaries and log files.

==Image Information==

This chapter provides details about the Docker image used for the innovaphone App Platform.

===Repository Details===

;Repository Host : docker.innovaphone.com
;Image Name : cloud/kubernetes/innovaphone-platform-instance

docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

===Tagging and Versioning===
The image is usually tagged with the build number according to innovaphone software releases:

;Latest Tag : Use the latest tag for pulling the most recent service release.

;Release Build Number : For production or version-specific deployments, use a specific build number as the tag (e.g., 130006).

Example:
docker pull docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

===Supported Architecture===
This Docker image supports the <code>linux/amd64</code> architecture.

===Image Reference===
An example of a full image reference using a specific release build number would be:
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

==Ports==
This chapter outlines the various ports exposed by the container. The webserver ports are available immediately upon container startup, after start of the AP Manager and the Webserver, while the additional application ports become active after the app installation. In most cases, a one-to-one mapping is used, meaning the container port is mapped directly to the same host port unless otherwise specified.

===Ports < 1024===
On most docker hosts, a container won't be able to use ports below 1024, unless the container is started with higher privileges.
This shouldn't be neccessary anyways as all ports can be configured to higher ports.

===Webserver Ports===
;HTTP:
Container Port: 8080
Description: Used for accessing the built-in webserver immediately upon container startup.

;HTTPS:
Container Port: 8082
Description: Used for accessing the built-in webserver immediately upon container startup.

=== Additional Application Ports===
Following additional container ports are avilable depending on installed and configured applications:
;H323/TLS : 1300
;SIP : 5060
;SIPS : 5061
;LDAPS : 1636
;SMTP : 8025
;SMTPS : 8587
;STUN/TURN : 3478 UDP/TCP
'''Additional hint for Portmapping'''<syntaxhighlight lang="yaml" line="1">
docker run -d \
--name=innovaphone \
--restart unless-stopped \
-p 9090:8080 \ #Container Host Port (external) 9090:8080 Container Port
-p 9091:8082 \
-p 5060:5060 \
-p 5061:5061 \
-p 1300:1300 \
-p 1636:1636 \
-p 8025:8025 \
-p 8587:8587 \
-p 3478:3478 \
-p 3478:3478/udp \
-v /path/of/data/innovaphone:/mnt/data \ #in this path you will find Apps, DBs & Logs
#this path musst be used for backups!!
-e WEBSERVERPORTHTTP=8080 \
-e WEBSERVERPORTHTTPS=8082 \
-e LOG_FLAGS=7 \
-e LOG_SIZE=1048576 \
-e DNSIPV4=8.8.8.8 \
-e LIMIT_RAM=512 \ #Ram limit in MB
-e LIMIT_DISK=10 \ #disk size in GB
-e TZ=Europe/Berlin \
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

</syntaxhighlight>

==Environment Variables (ENVs)==
This chapter outlines the key environment variables used to configure the behavior of the innovaphone App Platform Container. These variables allow you to customize logging, port settings, resource limits, and more during startup and runtime.

;LOG_FLAGS : Defines the integer representation for the trace flags of the AP Manager, according flags activated under the AP Manager / Diagnostics. See browser console message on Save button press (e.g. "logFlags":1 , if the "App" flag is activated).
LOG_FLAGS=7
;LOG_SIZE : Specifies the maximum size in bytes for logs before rotation or management actions occur. Default: 5242880.
LOG_SIZE=1048576
;WEBSERVERPORTHTTP : Sets the in-container HTTP port for the webserver. Default: 8080.
WEBSERVERPORTHTTP=8080
;WEBSERVERPORTHTTPS : Sets the in-container HTTPS port for the webserver. Default: 8082.
WEBSERVERPORTHTTPS=8443
;DNSIPV4 : Specifies the in-container DNS server IPv4 address for DNS resolution. Overrides the default container runtime DNS server.
DNSIPV4=8.8.8.8
;DNS_DOMAIN : The FQDN of the App Platform that can be used to access the app services. This optional parameter is used as a static DNS entry added to /etc/hosts. The destination IP address is the resolved IP address behind INTERNAL_DNS_DOMAIN or NAMESPACE.
DNS_DOMAIN=ap.example.com
;INTERNAL_DNS_DOMAIN : The internal FQDN of the App Platform. This FQDN is used to resolve the internal IP address of the App Platform, to be mapped from DNS_DOMAIN in /etc/hosts.
INTERNAL_DNS_DOMAIN=my-apps-deployment.my-namespace.svc.cluster.local
;NAMESPACE : The Kubernetes namespace used to build internal FQDN of the App Platform. Used with DNS_DOMAIN to map it to the IP address of ap.my-namespace.svc.cluster.local.
NAMESPACE=my-namespace
;LIMIT_RAM : Sets the RAM limit for the container, in MB, controlling how much memory it may consume. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_RAM=512
;LIMIT_DISK : Defines the disk space limit in GB for the container to manage storage consumption. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_DISK=10

==File limits==
Containers may have a default file limit per process, e.g. 1024 files. Depending on your installation and usage, this value is too small and you need to allow more, e.g. handing this in the docker run command:
--ulimit nofile=1000000:1000000

==Volumes and Mounts==
This container uses a dedicated internal mount path for the persistent data management across container restarts and updates.

===Internal Data Volume===
;Mount Path : <code>/mnt/data</code>
;Contents:
*Apps: Installed application binaries.
*Databases: PostgreSQL files.
*Logging: Log files for system and application events.

===Mounting===
To ensure that your data is preserved, map a host directory or Docker named volume to the container's /mnt/data path when running the container.
For example:
docker run -d -v /path/on/host:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

This setup guarantees that your apps, associated data, databases, and logs persist independently of the container lifecycle.

==Entrypoint==
The container uses a fixed entrypoint:
ENTRYPOINT ["/entrypoint.sh"]

This script prepares the container and starts the AP Manager executable.

==Logging and Monitoring==
The log of the entrypoint.sh and of the AP manager is avilable as conatiner output. The installed applications store the ir log files under <code>/mnt/data/var/log/apps/</code>.

=== Unexpected high system load ===
If you encounter a high load, you need to verify whether the load is actually coming from your container. Docker containers always display the load of the physical host system.

It may be that the Docker host itself is also virtualized as an LXC container, and your Docker instances are running within it. In such a setup, the system load of the physical host is displayed because <code>/proc/loadavg</code> is not isolated per logical layer.

An increased load in the container therefore does not automatically mean that the container itself is the cause or that you have a problem at all. In short: To assess the load, you always need information (e.g., number of CPU cores or I/O information) from the physical host.

==Usage Example==
sudo docker run -d --ulimit nofile=1000000:1000000 --restart unless-stopped --name innovaphoneAP -p 9090:8080 -p 9091:8082 -e WEBSERVERPORTHTTP=8080 -e WEBSERVERPORTHTTPS=8082 -v $(pwd)/myapps/:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

This command runs the container in detached mode with automatic restart. It names the container innovaphoneAP, maps host ports 9090 and 9091 to the container's HTTP and HTTPS ports, sets the webserver port environment variables, mounts a host directory to /mnt/data, and starts the AP Manager. After container start up the AP manager web UI is accessible via <code>http://localhost:9090</code> or <code>https://localhost:9091</code>.

Reference16r1:Concept innovaphone App Platform Container

2026-03-19T08:40:10Z

Dde:

{{FIXME|reason=Below described feature is experimental and not officially supported for use in productive environments.}}
The innovaphone App Platform Container provides a myApps App Platform instance that includes the AP Manager, Webserver and PostgreSQL. This container offers a ready-to-use environment for myApps applications and the innovaphone PBX.

== Applies To ==

* innovaphone App Platform Container

==Requirements==
* Host with docker on a x86_64 (amd64) platform
* innovaphone App Platform Container

==Concept==

The innovaphone App Platform Container provides the innovaphone App Platform for container environments (Open Container Initiative (OCI) format).

* The App Platform Manager and Webserver Apps are already integrated in the container and provide the already known functionality.
* Apps are installed, updated and managed as usual.
* The mount point will be used for the database, the App binaries and log files.

==Image Information==

This chapter provides details about the Docker image used for the innovaphone App Platform.

===Repository Details===

;Repository Host : docker.innovaphone.com
;Image Name : cloud/kubernetes/innovaphone-platform-instance

docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

===Tagging and Versioning===
The image is usually tagged with the build number according to innovaphone software releases:

;Latest Tag : Use the latest tag for pulling the most recent service release.

;Release Build Number : For production or version-specific deployments, use a specific build number as the tag (e.g., 130006).

Example:
docker pull docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

===Supported Architecture===
This Docker image supports the <code>linux/amd64</code> architecture.

===Image Reference===
An example of a full image reference using a specific release build number would be:
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

==Ports==
This chapter outlines the various ports exposed by the container. The webserver ports are available immediately upon container startup, after start of the AP Manager and the Webserver, while the additional application ports become active after the app installation. In most cases, a one-to-one mapping is used, meaning the container port is mapped directly to the same host port unless otherwise specified.

===Ports < 1024===
On most docker hosts, a container won't be able to use ports below 1024, unless the container is started with higher privileges.
This shouldn't be neccessary anyways as all ports can be configured to higher ports.

===Webserver Ports===
;HTTP:
Container Port: 8080
Description: Used for accessing the built-in webserver immediately upon container startup.

;HTTPS:
Container Port: 8082
Description: Used for accessing the built-in webserver immediately upon container startup.

=== Additional Application Ports===
Following additional container ports are avilable depending on installed and configured applications:
;H323/TLS : 1300
;SIP : 5060
;SIPS : 5061
;LDAPS : 1636
;SMTP : 8025
;SMTPS : 8587
;STUN/TURN : 3478 UDP/TCP
'''Additional hint for Portmapping'''<syntaxhighlight lang="yaml" line="1">
docker run -d \
--name=innovaphone \
--restart unless-stopped \
-p 9090:8080 \ #Container Host Port (external) 9090:8080 Container Port
-p 9091:8082 \
-p 5060:5060 \
-p 5061:5061 \
-p 1300:1300 \
-p 1636:1636 \
-p 8025:8025 \
-p 8587:8587 \
-p 3478:3478 \
-p 3478:3478/udp \
-v /path/of/data/innovaphone:/mnt/data \ #in this path you will find Apps, DBs & Logs
#this path musst be used for backups!!
-e WEBSERVERPORTHTTP=8080 \
-e WEBSERVERPORTHTTPS=8082 \
-e LOG_FLAGS=7 \
-e LOG_SIZE=1048576 \
-e DNSIPV4=8.8.8.8 \
-e LIMIT_RAM=512 \ #Ram limit in MB
-e LIMIT_DISK=10 \ #disk size in GB
-e TZ=Europe/Berlin \
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

</syntaxhighlight>

==Environment Variables (ENVs)==
This chapter outlines the key environment variables used to configure the behavior of the innovaphone App Platform Container. These variables allow you to customize logging, port settings, resource limits, and more during startup and runtime.

;LOG_FLAGS : Defines the integer representation for the trace flags of the AP Manager, according flags activated under the AP Manager / Diagnostics. See browser console message on Save button press (e.g. "logFlags":1 , if the "App" flag is activated).
LOG_FLAGS=7
;LOG_SIZE : Specifies the maximum size in bytes for logs before rotation or management actions occur. Default: 5242880.
LOG_SIZE=1048576
;WEBSERVERPORTHTTP : Sets the in-container HTTP port for the webserver. Default: 8080.
WEBSERVERPORTHTTP=8080
;WEBSERVERPORTHTTPS : Sets the in-container HTTPS port for the webserver. Default: 8082.
WEBSERVERPORTHTTPS=8443
;DNSIPV4 : Specifies the in-container DNS server IPv4 address for DNS resolution. Overrides the default container runtime DNS server.
DNSIPV4=8.8.8.8
;DNS_DOMAIN : The FQDN of the App Platform that can be used to access the app services. This optional parameter is used as a static DNS entry added to /etc/hosts. The destination IP address is the resolved IP address behind INTERNAL_DNS_DOMAIN or NAMESPACE.
DNS_DOMAIN=ap.example.com
;INTERNAL_DNS_DOMAIN : The internal FQDN of the App Platform. This FQDN is used to resolve the internal IP address of the App Platform, to be mapped from DNS_DOMAIN in /etc/hosts.
INTERNAL_DNS_DOMAIN=my-apps-deployment.my-namespace.svc.cluster.local
;NAMESPACE : The Kubernetes namespace used to build internal FQDN of the App Platform. Used with DNS_DOMAIN to map it to the IP address of ap.my-namespace.svc.cluster.local.
NAMESPACE=my-namespace
;LIMIT_RAM : Sets the RAM limit for the container, in MB, controlling how much memory it may consume. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_RAM=512
;LIMIT_DISK : Defines the disk space limit in GB for the container to manage storage consumption. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_DISK=10

==Volumes and Mounts==
This container uses a dedicated internal mount path for the persistent data management across container restarts and updates.

===Internal Data Volume===
;Mount Path : <code>/mnt/data</code>
;Contents:
*Apps: Installed application binaries.
*Databases: PostgreSQL files.
*Logging: Log files for system and application events.

===Mounting===
To ensure that your data is preserved, map a host directory or Docker named volume to the container's /mnt/data path when running the container.
For example:
docker run -d -v /path/on/host:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

This setup guarantees that your apps, associated data, databases, and logs persist independently of the container lifecycle.

==Entrypoint==
The container uses a fixed entrypoint:
ENTRYPOINT ["/entrypoint.sh"]

This script prepares the container and starts the AP Manager executable.

==Logging and Monitoring==
The log of the entrypoint.sh and of the AP manager is avilable as conatiner output. The installed applications store the ir log files under <code>/mnt/data/var/log/apps/</code>.

==Usage Example==
sudo docker run -d --restart unless-stopped --name innovaphoneAP -p 9090:8080 -p 9091:8082 -e WEBSERVERPORTHTTP=8080 -e WEBSERVERPORTHTTPS=8082 -v $(pwd)/myapps/:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

This command runs the container in detached mode with automatic restart. It names the container innovaphoneAP, maps host ports 9090 and 9091 to the container's HTTP and HTTPS ports, sets the webserver port environment variables, mounts a host directory to /mnt/data, and starts the AP Manager. After container start up the AP manager web UI is accessible via <code>http://localhost:9090</code> or <code>https://localhost:9091</code>.

Reference16r1:Concept innovaphone App Platform Container

2026-03-19T08:38:39Z

Dde: Dde moved page Reference16r1:Concept innovaphone App Platform Docker Container to Reference16r1:Concept innovaphone App Platform Container

{{FIXME|reason=Below described feature is experimental and not officially supported for use in productive environments.}}
The innovaphone App Platform Docker container provides a myApps App Platform instance that includes the AP Manager, Webserver and PostgreSQL. This container offers a ready-to-use environment for myApps applications and the innovaphone PBX.

== Applies To ==

* innovaphone App Platform Docker Container

==Requirements==
* Host with docker on a x86_64 (amd64) platform
* innovaphone App Platform Docker Container

==Concept==

The innovaphone App Platform Docker Container provides the innovaphone App Platform for docker environments.

* The App Platform Manager and Webserver Apps are already integrated in the container and provide the already known functionality.
* Apps are installed, updated and managed as usual.
* The mount point will be used for the database, the App binaries and log files.

==Image Information==

This chapter provides details about the Docker image used for the innovaphone App Platform.

===Repository Details===

;Repository Host : docker.innovaphone.com
;Image Name : cloud/kubernetes/innovaphone-platform-instance

docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

===Tagging and Versioning===
The image is usually tagged with the build number according to innovaphone software releases:

;Latest Tag : Use the latest tag for pulling the most recent service release.

;Release Build Number : For production or version-specific deployments, use a specific build number as the tag (e.g., 130006).

Example:
docker pull docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

===Supported Architecture===
This Docker image supports the <code>linux/amd64</code> architecture.

===Image Reference===
An example of a full image reference using a specific release build number would be:
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

==Ports==
This chapter outlines the various ports exposed by the Docker container. The webserver ports are available immediately upon container startup, after start of the AP Manager and the Webserver, while the additional application ports become active after the app installation. In most cases, a one-to-one mapping is used, meaning the container port is mapped directly to the same host port unless otherwise specified.

===Ports < 1024===
On most docker hosts, a container won't be able to use ports below 1024, unless the container is started with higher privileges.
This shouldn't be neccessary anyways as all ports can be configured to higher ports.

===Webserver Ports===
;HTTP:
Container Port: 8080
Description: Used for accessing the built-in webserver immediately upon container startup.

;HTTPS:
Container Port: 8082
Description: Used for accessing the built-in webserver immediately upon container startup.

=== Additional Application Ports===
Following additional container ports are avilable depending on installed and configured applications:
;H323/TLS : 1300
;SIP : 5060
;SIPS : 5061
;LDAPS : 1636
;SMTP : 8025
;SMTPS : 8587
;STUN/TURN : 3478 UDP/TCP
'''Additional hint for Portmapping'''<syntaxhighlight lang="yaml" line="1">
docker run -d \
--name=innovaphone \
--restart unless-stopped \
-p 9090:8080 \ #Container Host Port (external) 9090:8080 Container Port
-p 9091:8082 \
-p 5060:5060 \
-p 5061:5061 \
-p 1300:1300 \
-p 1636:1636 \
-p 8025:8025 \
-p 8587:8587 \
-p 3478:3478 \
-p 3478:3478/udp \
-v /path/of/data/innovaphone:/mnt/data \ #in this path you will find Apps, DBs & Logs
#this path musst be used for backups!!
-e WEBSERVERPORTHTTP=8080 \
-e WEBSERVERPORTHTTPS=8082 \
-e LOG_FLAGS=7 \
-e LOG_SIZE=1048576 \
-e DNSIPV4=8.8.8.8 \
-e LIMIT_RAM=512 \ #Ram limit in MB
-e LIMIT_DISK=10 \ #disk size in GB
-e TZ=Europe/Berlin \
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

</syntaxhighlight>

==Environment Variables (ENVs)==
This chapter outlines the key environment variables used to configure the behavior of the innovaphone App Platform Docker container. These variables allow you to customize logging, port settings, resource limits, and more during startup and runtime.

;LOG_FLAGS : Defines the integer representation for the trace flags of the AP Manager, according flags activated under the AP Manager / Diagnostics. See browser console message on Save button press (e.g. "logFlags":1 , if the "App" flag is activated).
LOG_FLAGS=7
;LOG_SIZE : Specifies the maximum size in bytes for logs before rotation or management actions occur. Default: 5242880.
LOG_SIZE=1048576
;WEBSERVERPORTHTTP : Sets the in-container HTTP port for the webserver. Default: 8080.
WEBSERVERPORTHTTP=8080
;WEBSERVERPORTHTTPS : Sets the in-container HTTPS port for the webserver. Default: 8082.
WEBSERVERPORTHTTPS=8443
;DNSIPV4 : Specifies the in-container DNS server IPv4 address for DNS resolution. Overrides the default container runtime DNS server.
DNSIPV4=8.8.8.8
;DNS_DOMAIN : The FQDN of the App Platform that can be used to access the app services. This optional parameter is used as a static DNS entry added to /etc/hosts. The destination IP address is the resolved IP address behind INTERNAL_DNS_DOMAIN or NAMESPACE.
DNS_DOMAIN=ap.example.com
;INTERNAL_DNS_DOMAIN : The internal FQDN of the App Platform. This FQDN is used to resolve the internal IP address of the App Platform, to be mapped from DNS_DOMAIN in /etc/hosts.
INTERNAL_DNS_DOMAIN=my-apps-deployment.my-namespace.svc.cluster.local
;NAMESPACE : The Kubernetes namespace used to build internal FQDN of the App Platform. Used with DNS_DOMAIN to map it to the IP address of ap.my-namespace.svc.cluster.local.
NAMESPACE=my-namespace
;LIMIT_RAM : Sets the RAM limit for the container, in MB, controlling how much memory it may consume. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_RAM=512
;LIMIT_DISK : Defines the disk space limit in GB for the container to manage storage consumption. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_DISK=10

==Volumes and Mounts==
This container uses a dedicated internal mount path for the persistent data management across container restarts and updates.

===Internal Data Volume===
;Mount Path : <code>/mnt/data</code>
;Contents:
*Apps: Installed application binaries.
*Databases: PostgreSQL files.
*Logging: Log files for system and application events.

===Mounting===
To ensure that your data is preserved, map a host directory or Docker named volume to the container's /mnt/data path when running the container.
For example:
docker run -d -v /path/on/host:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

This setup guarantees that your apps, associated data, databases, and logs persist independently of the container lifecycle.

==Entrypoint==
The container uses a fixed entrypoint:
ENTRYPOINT ["/entrypoint.sh"]

This script prepares the container and starts the AP Manager executable.

==Logging and Monitoring==
The log of the entrypoint.sh and of the AP manager is avilable as conatiner output. The installed applications store the ir log files under <code>/mnt/data/var/log/apps/</code>.

==Usage Example==
sudo docker run -d --restart unless-stopped --name innovaphoneAP -p 9090:8080 -p 9091:8082 -e WEBSERVERPORTHTTP=8080 -e WEBSERVERPORTHTTPS=8082 -v $(pwd)/myapps/:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

This command runs the container in detached mode with automatic restart. It names the container innovaphoneAP, maps host ports 9090 and 9091 to the container's HTTP and HTTPS ports, sets the webserver port environment variables, mounts a host directory to /mnt/data, and starts the AP Manager. After container start up the AP manager web UI is accessible via <code>http://localhost:9090</code> or <code>https://localhost:9091</code>.

Reference16r1:Concept innovaphone App Platform Container

2026-03-18T10:22:23Z

Dde: /* Requirements */

Reference16r1:Concept innovaphone App Platform Container

2026-03-17T08:08:18Z

Dde:

{{FIXME|reason=Below described feature is experimental and not officially supported for use in productive environments.}}
The innovaphone App Platform Docker container provides a myApps App Platform instance that includes the AP Manager, Webserver and PostgreSQL. This container offers a ready-to-use environment for myApps applications and the innovaphone PBX.

== Applies To ==

* innovaphone App Platform Docker Container

==Requirements==
* Host with docker on a x86_64 (arm64) platform
* innovaphone App Platform Docker Container

==Concept==

The innovaphone App Platform Docker Container provides the innovaphone App Platform for docker environments.

* The App Platform Manager and Webserver Apps are already integrated in the container and provide the already known functionality.
* Apps are installed, updated and managed as usual.
* The mount point will be used for the database, the App binaries and log files.

==Image Information==

This chapter provides details about the Docker image used for the innovaphone App Platform.

===Repository Details===

;Repository Host : docker.innovaphone.com
;Image Name : cloud/kubernetes/innovaphone-platform-instance

docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

===Tagging and Versioning===
The image is usually tagged with the build number according to innovaphone software releases:

;Latest Tag : Use the latest tag for pulling the most recent service release.

;Release Build Number : For production or version-specific deployments, use a specific build number as the tag (e.g., 130006).

Example:
docker pull docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

===Supported Architecture===
This Docker image supports the <code>linux/amd64</code> architecture.

===Image Reference===
An example of a full image reference using a specific release build number would be:
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

==Ports==
This chapter outlines the various ports exposed by the Docker container. The webserver ports are available immediately upon container startup, after start of the AP Manager and the Webserver, while the additional application ports become active after the app installation. In most cases, a one-to-one mapping is used, meaning the container port is mapped directly to the same host port unless otherwise specified.

===Ports < 1024===
On most docker hosts, a container won't be able to use ports below 1024, unless the container is started with higher privileges.
This shouldn't be neccessary anyways as all ports can be configured to higher ports.

===Webserver Ports===
;HTTP:
Container Port: 8080
Description: Used for accessing the built-in webserver immediately upon container startup.

;HTTPS:
Container Port: 8082
Description: Used for accessing the built-in webserver immediately upon container startup.

=== Additional Application Ports===
Following additional container ports are avilable depending on installed and configured applications:
;H323/TLS : 1300
;SIP : 5060
;SIPS : 5061
;LDAPS : 1636
;SMTP : 8025
;SMTPS : 8587
'''Additional hint for Portmapping'''<syntaxhighlight lang="yaml" line="1">
docker run -d \
--name=innovaphone \
--restart unless-stopped \
-p 9090:8080 \ #Container Host Port (external) 9090:8080 Container Port
-p 9091:8082 \
-p 5060:5060 \
-p 5061:5061 \
-p 1300:1300 \
-p 1636:1636 \
-p 8025:8025 \
-p 8587:8587 \
-v /path/of/data/innovaphone:/mnt/data \ #in this path you will find Apps, DBs & Logs
#this path musst be used for backups!!
-e WEBSERVERPORTHTTP=8080 \
-e WEBSERVERPORTHTTPS=8082 \
-e LOG_FLAGS=7 \
-e LOG_SIZE=1048576 \
-e DNSIPV4=8.8.8.8 \
-e LIMIT_RAM=512 \ #Ram limit in MB
-e LIMIT_DISK=10 \ #disk size in GB
-e TZ=Europe/Berlin \
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

</syntaxhighlight>

==Environment Variables (ENVs)==
This chapter outlines the key environment variables used to configure the behavior of the innovaphone App Platform Docker container. These variables allow you to customize logging, port settings, resource limits, and more during startup and runtime.

;LOG_FLAGS : Defines the integer representation for the trace flags of the AP Manager, according flags activated under the AP Manager / Diagnostics. See browser console message on Save button press (e.g. "logFlags":1 , if the "App" flag is activated).
LOG_FLAGS=7
;LOG_SIZE : Specifies the maximum size in bytes for logs before rotation or management actions occur. Default: 5242880.
LOG_SIZE=1048576
;WEBSERVERPORTHTTP : Sets the in-container HTTP port for the webserver. Default: 8080.
WEBSERVERPORTHTTP=8080
;WEBSERVERPORTHTTPS : Sets the in-container HTTPS port for the webserver. Default: 8082.
WEBSERVERPORTHTTPS=8443
;DNSIPV4 : Specifies the in-container DNS server IPv4 address for DNS resolution. Overrides the default container runtime DNS server.
DNSIPV4=8.8.8.8
;DNS_DOMAIN : The FQDN of the App Platform that can be used to access the app services. This optional parameter is used as a static DNS entry added to /etc/hosts. The destination IP address is the resolved IP address behind INTERNAL_DNS_DOMAIN or NAMESPACE.
DNS_DOMAIN=ap.example.com
;INTERNAL_DNS_DOMAIN : The internal FQDN of the App Platform. This FQDN is used to resolve the internal IP address of the App Platform, to be mapped from DNS_DOMAIN in /etc/hosts.
INTERNAL_DNS_DOMAIN=my-apps-deployment.my-namespace.svc.cluster.local
;NAMESPACE : The Kubernetes namespace used to build internal FQDN of the App Platform. Used with DNS_DOMAIN to map it to the IP address of ap.my-namespace.svc.cluster.local.
NAMESPACE=my-namespace
;LIMIT_RAM : Sets the RAM limit for the container, in MB, controlling how much memory it may consume. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_RAM=512
;LIMIT_DISK : Defines the disk space limit in GB for the container to manage storage consumption. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_DISK=10

==Volumes and Mounts==
This container uses a dedicated internal mount path for the persistent data management across container restarts and updates.

===Internal Data Volume===
;Mount Path : <code>/mnt/data</code>
;Contents:
*Apps: Installed application binaries.
*Databases: PostgreSQL files.
*Logging: Log files for system and application events.

===Mounting===
To ensure that your data is preserved, map a host directory or Docker named volume to the container's /mnt/data path when running the container.
For example:
docker run -d -v /path/on/host:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

This setup guarantees that your apps, associated data, databases, and logs persist independently of the container lifecycle.

==Entrypoint==
The container uses a fixed entrypoint:
ENTRYPOINT ["/entrypoint.sh"]

This script prepares the container and starts the AP Manager executable.

==Logging and Monitoring==
The log of the entrypoint.sh and of the AP manager is avilable as conatiner output. The installed applications store the ir log files under <code>/mnt/data/var/log/apps/</code>.

==Usage Example==
sudo docker run -d --restart unless-stopped --name innovaphoneAP -p 9090:8080 -p 9091:8082 -e WEBSERVERPORTHTTP=8080 -e WEBSERVERPORTHTTPS=8082 -v $(pwd)/myapps/:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

This command runs the container in detached mode with automatic restart. It names the container innovaphoneAP, maps host ports 9090 and 9091 to the container's HTTP and HTTPS ports, sets the webserver port environment variables, mounts a host directory to /mnt/data, and starts the AP Manager. After container start up the AP manager web UI is accessible via <code>http://localhost:9090</code> or <code>https://localhost:9091</code>.

Reference16r1:Concept innovaphone App Platform Container

2026-03-17T08:01:19Z

Dde: /* Environment Variables (ENVs) */

{{FIXME|reason=Below described feature is experimental and not officially supported for use in productive environments.}}
The innovaphone App Platform Docker container provides a myApps App Platform instance that includes the AP Manager, Webserver and PostgreSQL. This container offers a ready-to-use environment for myApps applications and the innovaphone PBX.

==Image Information==

This chapter provides details about the Docker image used for the innovaphone App Platform.

===Repository Details===

;Repository Host : docker.innovaphone.com
;Image Name : cloud/kubernetes/innovaphone-platform-instance

docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

===Tagging and Versioning===
The image is usually tagged with the build number according to innovaphone software releases:

;Latest Tag : Use the latest tag for pulling the most recent service release.

;Release Build Number : For production or version-specific deployments, use a specific build number as the tag (e.g., 130006).

Example:
docker pull docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

===Supported Architecture===
This Docker image supports the <code>linux/amd64</code> architecture.

===Image Reference===
An example of a full image reference using a specific release build number would be:
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

==Ports==
This chapter outlines the various ports exposed by the Docker container. The webserver ports are available immediately upon container startup, after start of the AP Manager and the Webserver, while the additional application ports become active after the app installation. In most cases, a one-to-one mapping is used, meaning the container port is mapped directly to the same host port unless otherwise specified.

===Ports < 1024===
On most docker hosts, a container won't be able to use ports below 1024, unless the container is started with higher privileges.
This shouldn't be neccessary anyways as all ports can be configured to higher ports.

===Webserver Ports===
;HTTP:
Container Port: 8080
Description: Used for accessing the built-in webserver immediately upon container startup.

;HTTPS:
Container Port: 8082
Description: Used for accessing the built-in webserver immediately upon container startup.

=== Additional Application Ports===
Following additional container ports are avilable depending on installed and configured applications:
;H323/TLS : 1300
;SIP : 5060
;SIPS : 5061
;LDAPS : 1636
;SMTP : 8025
;SMTPS : 8587
'''Additional hint for Portmapping'''<syntaxhighlight lang="yaml" line="1">
docker run -d \
--name=innovaphone \
--restart unless-stopped \
-p 9090:8080 \ #Container Host Port (external) 9090:8080 Container Port
-p 9091:8082 \
-p 5060:5060 \
-p 5061:5061 \
-p 1300:1300 \
-p 1636:1636 \
-p 8025:8025 \
-p 8587:8587 \
-v /path/of/data/innovaphone:/mnt/data \ #in this path you will find Apps, DBs & Logs
#this path musst be used for backups!!
-e WEBSERVERPORTHTTP=8080 \
-e WEBSERVERPORTHTTPS=8082 \
-e LOG_FLAGS=7 \
-e LOG_SIZE=1048576 \
-e DNSIPV4=8.8.8.8 \
-e LIMIT_RAM=512 \ #Ram limit in MB
-e LIMIT_DISK=10 \ #disk size in GB
-e TZ=Europe/Berlin \
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

</syntaxhighlight>

==Environment Variables (ENVs)==
This chapter outlines the key environment variables used to configure the behavior of the innovaphone App Platform Docker container. These variables allow you to customize logging, port settings, resource limits, and more during startup and runtime.

;LOG_FLAGS : Defines the integer representation for the trace flags of the AP Manager, according flags activated under the AP Manager / Diagnostics. See browser console message on Save button press (e.g. "logFlags":1 , if the "App" flag is activated).
LOG_FLAGS=7
;LOG_SIZE : Specifies the maximum size in bytes for logs before rotation or management actions occur. Default: 5242880.
LOG_SIZE=1048576
;WEBSERVERPORTHTTP : Sets the in-container HTTP port for the webserver. Default: 8080.
WEBSERVERPORTHTTP=8080
;WEBSERVERPORTHTTPS : Sets the in-container HTTPS port for the webserver. Default: 8082.
WEBSERVERPORTHTTPS=8443
;DNSIPV4 : Specifies the in-container DNS server IPv4 address for DNS resolution. Overrides the default container runtime DNS server.
DNSIPV4=8.8.8.8
;DNS_DOMAIN : The FQDN of the App Platform that can be used to access the app services. This optional parameter is used as a static DNS entry added to /etc/hosts. The destination IP address is the resolved IP address behind INTERNAL_DNS_DOMAIN or NAMESPACE.
DNS_DOMAIN=ap.example.com
;INTERNAL_DNS_DOMAIN : The internal FQDN of the App Platform. This FQDN is used to resolve the internal IP address of the App Platform, to be mapped from DNS_DOMAIN in /etc/hosts.
INTERNAL_DNS_DOMAIN=my-apps-deployment.my-namespace.svc.cluster.local
;NAMESPACE : The Kubernetes namespace used to build internal FQDN of the App Platform. Used with DNS_DOMAIN to map it to the IP address of ap.my-namespace.svc.cluster.local.
NAMESPACE=my-namespace
;LIMIT_RAM : Sets the RAM limit for the container, in MB, controlling how much memory it may consume. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_RAM=512
;LIMIT_DISK : Defines the disk space limit in GB for the container to manage storage consumption. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_DISK=10

==Volumes and Mounts==
This container uses a dedicated internal mount path for the persistent data management across container restarts and updates.

===Internal Data Volume===
;Mount Path : <code>/mnt/data</code>
;Contents:
*Apps: Installed application binaries.
*Databases: PostgreSQL files.
*Logging: Log files for system and application events.

===Mounting===
To ensure that your data is preserved, map a host directory or Docker named volume to the container's /mnt/data path when running the container.
For example:
docker run -d -v /path/on/host:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

This setup guarantees that your apps, associated data, databases, and logs persist independently of the container lifecycle.

==Entrypoint==
The container uses a fixed entrypoint:
ENTRYPOINT ["/entrypoint.sh"]

This script prepares the container and starts the AP Manager executable.

==Logging and Monitoring==
The log of the entrypoint.sh and of the AP manager is avilable as conatiner output. The installed applications store the ir log files under <code>/mnt/data/var/log/apps/</code>.

==Usage Example==
sudo docker run -d --restart unless-stopped --name innovaphoneAP -p 9090:8080 -p 9091:8082 -e WEBSERVERPORTHTTP=8080 -e WEBSERVERPORTHTTPS=8082 -v $(pwd)/myapps/:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

This command runs the container in detached mode with automatic restart. It names the container innovaphoneAP, maps host ports 9090 and 9091 to the container's HTTP and HTTPS ports, sets the webserver port environment variables, mounts a host directory to /mnt/data, and starts the AP Manager. After container start up the AP manager web UI is accessible via <code>http://localhost:9090</code> or <code>https://localhost:9091</code>.

Reference16r1:Concept innovaphone App Platform Container

2026-03-17T08:00:39Z

Dde: /* Environment Variables (ENVs) */

{{FIXME|reason=Below described feature is experimental and not officially supported for use in productive environments.}}
The innovaphone App Platform Docker container provides a myApps App Platform instance that includes the AP Manager, Webserver and PostgreSQL. This container offers a ready-to-use environment for myApps applications and the innovaphone PBX.

==Image Information==

This chapter provides details about the Docker image used for the innovaphone App Platform.

===Repository Details===

;Repository Host : docker.innovaphone.com
;Image Name : cloud/kubernetes/innovaphone-platform-instance

docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

===Tagging and Versioning===
The image is usually tagged with the build number according to innovaphone software releases:

;Latest Tag : Use the latest tag for pulling the most recent service release.

;Release Build Number : For production or version-specific deployments, use a specific build number as the tag (e.g., 130006).

Example:
docker pull docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

===Supported Architecture===
This Docker image supports the <code>linux/amd64</code> architecture.

===Image Reference===
An example of a full image reference using a specific release build number would be:
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

==Ports==
This chapter outlines the various ports exposed by the Docker container. The webserver ports are available immediately upon container startup, after start of the AP Manager and the Webserver, while the additional application ports become active after the app installation. In most cases, a one-to-one mapping is used, meaning the container port is mapped directly to the same host port unless otherwise specified.

===Ports < 1024===
On most docker hosts, a container won't be able to use ports below 1024, unless the container is started with higher privileges.
This shouldn't be neccessary anyways as all ports can be configured to higher ports.

===Webserver Ports===
;HTTP:
Container Port: 8080
Description: Used for accessing the built-in webserver immediately upon container startup.

;HTTPS:
Container Port: 8082
Description: Used for accessing the built-in webserver immediately upon container startup.

=== Additional Application Ports===
Following additional container ports are avilable depending on installed and configured applications:
;H323/TLS : 1300
;SIP : 5060
;SIPS : 5061
;LDAPS : 1636
;SMTP : 8025
;SMTPS : 8587
'''Additional hint for Portmapping'''<syntaxhighlight lang="yaml" line="1">
docker run -d \
--name=innovaphone \
--restart unless-stopped \
-p 9090:8080 \ #Container Host Port (external) 9090:8080 Container Port
-p 9091:8082 \
-p 5060:5060 \
-p 5061:5061 \
-p 1300:1300 \
-p 1636:1636 \
-p 8025:8025 \
-p 8587:8587 \
-v /path/of/data/innovaphone:/mnt/data \ #in this path you will find Apps, DBs & Logs
#this path musst be used for backups!!
-e WEBSERVERPORTHTTP=8080 \
-e WEBSERVERPORTHTTPS=8082 \
-e LOG_FLAGS=7 \
-e LOG_SIZE=1048576 \
-e DNSIPV4=8.8.8.8 \
-e LIMIT_RAM=512 \ #Ram limit in MB
-e LIMIT_DISK=10 \ #disk size in GB
-e TZ=Europe/Berlin \
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

</syntaxhighlight>

==Environment Variables (ENVs)==
This chapter outlines the key environment variables used to configure the behavior of the innovaphone App Platform Docker container. These variables allow you to customize logging, port settings, resource limits, and more during startup and runtime.

;LOG_FLAGS : Defines the integer representation for the trace flags of the AP Manager, according flags activated under the AP Manager / Diagnostics. See browser console message on Save button press (e.g. "logFlags":1 , if the "App" flag is activated).
LOG_FLAGS=7
;LOG_SIZE : Specifies the maximum size in bytes for logs before rotation or management actions occur. Default: 5242880.
LOG_SIZE=1048576
;WEBSERVERPORTHTTP : Sets the in-container HTTP port for the webserver. Default: 8080.
WEBSERVERPORTHTTP=8080
;WEBSERVERPORTHTTPS : Sets the in-container HTTPS port for the webserver. Default: 8082.
WEBSERVERPORTHTTPS=8443
;DNSIPV4 : Specifies the in-container DNS server IPv4 address for DNS resolution. Overrides the default container runtime DNS server.
DNSIPV4=8.8.8.8
;DNS_DOMAIN : The FQDN of the App Platform that can be used to access the app services. This optional parameter is used as a static DNS entry added to /etc/hosts. The destination IP address is the resolved IP address behind INTERNAL_DNS_DOMAIN or NAMESPACE.
DNS_DOMAIN=ap.example.com
;INTERNAL_DNS_DOMAIN : The internal FQDN of the App Platform. This FQDN is used to resolve the internal IP address of the App Platform, to be mapped from DNS_DOMAIN in /etc/hosts.
INTERNAL_DNS_DOMAIN=my-apps-deployment.my-namespace.svc.cluster.local
;NAMESPACE : The Kubernetes namespace used to build internal FQDN of the App Platform. Used with DNS_DOMAIN to map it to the IP address of ap.my-namespace.svc.cluster.local.
NAMESPACE=my-namespace
;LIMIT_RAM : Sets the RAM limit for the container, in MB, controlling how much memory it may consume. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_RAM=512
;LIMIT_DISK : Defines the disk space limit in GB for the container to manage storage consumption. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_DISK=10
;MANAGER_DB_HOST : defines an external database host for the database of the App Platform Manager
If you hand database settings, the container will work without the local database server and doesn't need any storage at all (under development).
MANAGER_DB_HOST=172.16.14.35:5432 (port is optional)
;MANAGER_DB_NAME : the external database name
MANAGER_DB_NAME=databasename
;MANAGER_DB_USER : the external database user who has access
MANAGER_DB_USER=databaseuser
;MANAGER_DB_PASSWORD : the password of the user
MANAGER_DB_PASSWORD=o1kk2hj312k3

==Volumes and Mounts==
This container uses a dedicated internal mount path for the persistent data management across container restarts and updates.

===Internal Data Volume===
;Mount Path : <code>/mnt/data</code>
;Contents:
*Apps: Installed application binaries.
*Databases: PostgreSQL files.
*Logging: Log files for system and application events.

===Mounting===
To ensure that your data is preserved, map a host directory or Docker named volume to the container's /mnt/data path when running the container.
For example:
docker run -d -v /path/on/host:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

This setup guarantees that your apps, associated data, databases, and logs persist independently of the container lifecycle.

==Entrypoint==
The container uses a fixed entrypoint:
ENTRYPOINT ["/entrypoint.sh"]

This script prepares the container and starts the AP Manager executable.

==Logging and Monitoring==
The log of the entrypoint.sh and of the AP manager is avilable as conatiner output. The installed applications store the ir log files under <code>/mnt/data/var/log/apps/</code>.

==Usage Example==
sudo docker run -d --restart unless-stopped --name innovaphoneAP -p 9090:8080 -p 9091:8082 -e WEBSERVERPORTHTTP=8080 -e WEBSERVERPORTHTTPS=8082 -v $(pwd)/myapps/:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

This command runs the container in detached mode with automatic restart. It names the container innovaphoneAP, maps host ports 9090 and 9091 to the container's HTTP and HTTPS ports, sets the webserver port environment variables, mounts a host directory to /mnt/data, and starts the AP Manager. After container start up the AP manager web UI is accessible via <code>http://localhost:9090</code> or <code>https://localhost:9091</code>.

Reference16r1:Concept innovaphone App Platform Container

2026-03-17T07:59:13Z

Dde: /* Ports */

{{FIXME|reason=Below described feature is experimental and not officially supported for use in productive environments.}}
The innovaphone App Platform Docker container provides a myApps App Platform instance that includes the AP Manager, Webserver and PostgreSQL. This container offers a ready-to-use environment for myApps applications and the innovaphone PBX.

==Image Information==

This chapter provides details about the Docker image used for the innovaphone App Platform.

===Repository Details===

;Repository Host : docker.innovaphone.com
;Image Name : cloud/kubernetes/innovaphone-platform-instance

docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

===Tagging and Versioning===
The image is usually tagged with the build number according to innovaphone software releases:

;Latest Tag : Use the latest tag for pulling the most recent service release.

;Release Build Number : For production or version-specific deployments, use a specific build number as the tag (e.g., 130006).

Example:
docker pull docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

===Supported Architecture===
This Docker image supports the <code>linux/amd64</code> architecture.

===Image Reference===
An example of a full image reference using a specific release build number would be:
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

==Ports==
This chapter outlines the various ports exposed by the Docker container. The webserver ports are available immediately upon container startup, after start of the AP Manager and the Webserver, while the additional application ports become active after the app installation. In most cases, a one-to-one mapping is used, meaning the container port is mapped directly to the same host port unless otherwise specified.

===Ports < 1024===
On most docker hosts, a container won't be able to use ports below 1024, unless the container is started with higher privileges.
This shouldn't be neccessary anyways as all ports can be configured to higher ports.

===Webserver Ports===
;HTTP:
Container Port: 8080
Description: Used for accessing the built-in webserver immediately upon container startup.

;HTTPS:
Container Port: 8082
Description: Used for accessing the built-in webserver immediately upon container startup.

=== Additional Application Ports===
Following additional container ports are avilable depending on installed and configured applications:
;H323/TLS : 1300
;SIP : 5060
;SIPS : 5061
;LDAPS : 1636
;SMTP : 8025
;SMTPS : 8587
'''Additional hint for Portmapping'''<syntaxhighlight lang="yaml" line="1">
docker run -d \
--name=innovaphone \
--restart unless-stopped \
-p 9090:8080 \ #Container Host Port (external) 9090:8080 Container Port
-p 9091:8082 \
-p 5060:5060 \
-p 5061:5061 \
-p 1300:1300 \
-p 1636:1636 \
-p 8025:8025 \
-p 8587:8587 \
-v /path/of/data/innovaphone:/mnt/data \ #in this path you will find Apps, DBs & Logs
#this path musst be used for backups!!
-e WEBSERVERPORTHTTP=8080 \
-e WEBSERVERPORTHTTPS=8082 \
-e LOG_FLAGS=7 \
-e LOG_SIZE=1048576 \
-e DNSIPV4=8.8.8.8 \
-e LIMIT_RAM=512 \ #Ram limit in MB
-e LIMIT_DISK=10 \ #disk size in GB
-e TZ=Europe/Berlin \
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

</syntaxhighlight>

==Environment Variables (ENVs)==
This chapter outlines the key environment variables used to configure the behavior of the innovaphone App Platform Docker container. These variables allow you to customize logging, port settings, resource limits, and more during startup and runtime.

;LOG_FLAGS : Defines the integer representation for the trace flags of the AP Manager, according flags activated under the AP Manager / Diagnostics. See browser console message on Save button press (e.g. "logFlags":1 , if the "App" flag is activated).
LOG_FLAGS=7
;LOG_SIZE : Specifies the maximum size in bytes for logs before rotation or management actions occur. Default: 5242880.
LOG_SIZE=1048576
;WEBSERVERPORTHTTP : Sets the in-container HTTP port for the webserver. Default: 8080.
WEBSERVERPORTHTTP=8080
;WEBSERVERPORTHTTPS : Sets the in-container HTTPS port for the webserver. Default: 8082.
WEBSERVERPORTHTTPS=8443
;DNSIPV4 : Specifies the in-container DNS server IPv4 address for DNS resolution. Overrides the default container runtime DNS server.
DNSIPV4=8.8.8.8
;DNS_DOMAIN : The FQDN of the App Platform that can be used to access the app services. This optional parameter is used as a static DNS entry added to /etc/hosts. The destination IP address is the resolved IP address behind INTERNAL_DNS_DOMAIN or NAMESPACE.
DNS_DOMAIN=ap.example.com
;INTERNAL_DNS_DOMAIN : The internal FQDN of the App Platform. This FQDN is used to resolve the internal IP address of the App Platform, to be mapped from DNS_DOMAIN in /etc/hosts.
INTERNAL_DNS_DOMAIN=my-apps-deployment.my-namespace.svc.cluster.local
;NAMESPACE : The Kubernetes namespace used to build internal FQDN of the App Platform. Used with DNS_DOMAIN to map it to the IP address of ap.my-namespace.svc.cluster.local.
NAMESPACE=my-namespace
;LIMIT_RAM : Sets the RAM limit for the container, in MB, controlling how much memory it may consume. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_RAM=512
;LIMIT_DISK : Defines the disk space limit in GB for the container to manage storage consumption. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_DISK=10
;MANAGER_DB_HOST : defines an external database host for the database of the App Platform Manager
If you hand database settings, the container will work without the local database server and doesn't need any storage at all (under development).
MANAGER_DB_HOST=172.16.14.35:5432 (port is optional)
;MANAGER_DB_NAME : the external database name
MANAGER_DB_NAME=databasename
;MANAGER_DB_USER : the external database user who has access
MANAGER_DB_USER=databaseuser
;MANAGER_DB_PASSWORD : the password of the user
MANAGER_DB_PASSWORD=o1kk2hj312k3
;DB_PROVISIONER_URL : a websocket URL to an external DBProvisioner App which is used to provide databases
DB_PROVISIONER_URL=wss://domain.com/domain.com/dbprovisioner

==Volumes and Mounts==
This container uses a dedicated internal mount path for the persistent data management across container restarts and updates.

===Internal Data Volume===
;Mount Path : <code>/mnt/data</code>
;Contents:
*Apps: Installed application binaries.
*Databases: PostgreSQL files.
*Logging: Log files for system and application events.

===Mounting===
To ensure that your data is preserved, map a host directory or Docker named volume to the container's /mnt/data path when running the container.
For example:
docker run -d -v /path/on/host:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

This setup guarantees that your apps, associated data, databases, and logs persist independently of the container lifecycle.

==Entrypoint==
The container uses a fixed entrypoint:
ENTRYPOINT ["/entrypoint.sh"]

This script prepares the container and starts the AP Manager executable.

==Logging and Monitoring==
The log of the entrypoint.sh and of the AP manager is avilable as conatiner output. The installed applications store the ir log files under <code>/mnt/data/var/log/apps/</code>.

==Usage Example==
sudo docker run -d --restart unless-stopped --name innovaphoneAP -p 9090:8080 -p 9091:8082 -e WEBSERVERPORTHTTP=8080 -e WEBSERVERPORTHTTPS=8082 -v $(pwd)/myapps/:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

This command runs the container in detached mode with automatic restart. It names the container innovaphoneAP, maps host ports 9090 and 9091 to the container's HTTP and HTTPS ports, sets the webserver port environment variables, mounts a host directory to /mnt/data, and starts the AP Manager. After container start up the AP manager web UI is accessible via <code>http://localhost:9090</code> or <code>https://localhost:9091</code>.

Reference14r2:Concept App Platform

2026-03-16T08:32:49Z

Dde: /* Gateway */

= General =
* V13 uses [https://buildroot.org/ buildroot]
* this is an own (innovaphone) collection of packages
* For further information see: [https://buildroot.org/docs.html Buildroot Documentations]

== Requirements ==

* V13 or above
* Gateway (arm): IPx10 (with CF card) or IPx11 (with mSATA SSD)
* Gateway (arm64): IPx13 (with m2 SSD)
* Virtual (x86_64)
** HyperV with [https://docs.microsoft.com/de-de/windows-server/virtualization/hyper-v/deploy/upgrade-virtual-machine-version-in-hyper-v-on-windows-or-windows-server#supported-virtual-machine-configuration-versions VM-configuration Version] 6.2 (minimum: Windows 10 or Windows Server 2016)
** VMWare
** Proxmox/KVM/Qemu

== Default credentials ==

'''During INSTALL, the default passwords are replaced with the global Admin PW!'''
* SSH-Login with '''admin''' and '''ipapps'''
* root login with '''root''' and '''iplinux''' (the root login is not directly possible, you have to login as admin first and use the command ''su root'')
* manager App (web login) '''pwd'''

= App Platform - arm/arm64 (Gateway)=

* The installation image has a size of ~50MB. During installation, the following partitions are created<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 fat32: 200MB (contains ramdisk, rootfs and kernel)
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB

When comparing potential performance of the IPxx11 platform compared to the IPxx10 platform, there are some major differences:
* SSDs found in the xx11 are faster and more reliable than the CF found in the xx10
* the available RAM for the App Platform (as specified in column ''RAM for LAP (GB) out of RAM'' in chapter ''Technical data and recommended number of users supported'' of [[Howto:How to implement large PBXs#Technical data and recommended number of users supported|How to implement large PBXs]]) is factor 6 larger on the xx11 (1,536 GB) than on the xx10 (0,256 GB))
* the xx11 has gigabit Ethernet while the xx10 has 100Mbps Ethernet. The xx10 is therefore not well suited for Apps with larger network traffic, such as Recordings
* the CPU of the xx11 (although it runs on the same frequency) is roughly 20% faster than the xx10

While it is hard to predict the performance of the App Platform in a specific scenario, we see that in a real life environment an App Platform running on an xx11 platform can well support 150 users. The xx10 platform is estimated to support 120 users. Because CPU performance is the limiting factor, larger setups can be built based on the virtual machine platform (see [[#App services and multi-threading|App services and multi-threading]] below).

<references/>

= App Platform - x86-64 (Virtual Machine 64bit) =

* The default disk size is 16GB. It should be increased '''before''' the first start if needed!
* Multiple CPUs are supported, default is one CPU
* default RAM: 512MB
* static IP address, DNS, Gateway can be configured with the command '''setip''' on the console. Run '''setip --help''' to get a list of parameters. (Example: setip --addr=x.x.x.x --mask=x.x.x.x --gateway=x.x.x.x --dns1=x.x.x.x)
* If you have permission problems change to su user (Password is iplinux or your new admin password)
* To figure out your ip address you can use the command: ''ip address'' on the console.
* '''loadkeys de''' can be used to change to german keyboard layout (etc.)
* partitions<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 ext2: 350MB (contains ramdisk, rootfs and kernel)
*** the real partition format size is smaller but there is no need to monitor sda1 as sda1 won't grow during usage of the App Platform
*** sda1 is completely exchanged during an image update and its size might have changed but will never exceed these 350MB
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB
* VMWare Tools: Open VM Tools
* Qemu Guest Agent: installed since 110032
** The qemu guest agent can be configured in Proxmox with ''Virtio'' or ''ISA''. Before version 130012, you must use ISA, as Virtio was not supported with older versions.

<references/>

= Installation =
==ARM Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-armel.img'' image file.
* The installation runs without any further required step.

==ARM64 Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-arm64.img'' image file.
* The installation runs without any further required step.

==Virtual machine==

* Import the image into your server environment.
** Proxmox: follow this description here, just with the app-platform-ova.zip: https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Proxmox_VE
* Edit the disk size, if needed.
* Start the machine and wait until it reboots and starts again.
* Note: If you need to access an IP addresses available through a VPN connection from from inside the virtual machine, it could be that you need to set the network of your VM to NAT (and also add the URL for an IP to /etc/hosts)

[https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Configuration More Configuration Hints regarding VM Ware]

== Backup of the Apps ==

Each App Service can have multiple instances and each instance has its own database. The manager app itself also has its own database. 
There are no other files which need to be backuped. 
The standard way to backup the databases is through the Devices App [[{{NAMESPACE}}:Concept_App_Service_Devices#Backups]]. 
 
An alternate way is to use a command file which is similar to the command files from the firmware.

===Commands===
* '''times''' 0,12 # backup only at 0 or 12 o'clock
* '''backup-instances''' http://user:pw@ip/path/#I-#D.dump PUT
** PUT and POST are supported, all instances including the manager itself are saved
* '''backup-instance''' http://user:pw@ip/path/#I-#D.dump apidemo example.com PUT
** backup a single instance with instance name and instance domain
* '''backup-manager''' http://user:pw@ip/path/#I-#D.dump

===Hash parameters===
* #L App Platform label (neu), e.g. 10024
* #A App label (neu), e.g. 130004
* #I instance name (neu), e.g. reporting1
* #D instance domain (neu), e.g. innovaphone.com
* #m MAC address of the LAP, e.g. 00ab11eeff
* #d Current date and time (plain UTC without daylight saving and timezone adjustments) 20051010-170130
* #bn rolling backup index (n >=0 and <= 9, just one digit)
* ## escapes a hash mark

= App Platform Infrastructure and Concept =
== Webserver ==
The app platform includes a webserver that is highly optimized for handling many Websocket connections at a low memory footprint.
All apps use that webserver by registering for specific HTTP subpath. So they can all use the same HTTP/HTTPS ports - typically the standard ports.

=== Import Custom SSL Certificate ===
You have to upload a PEM Certificate with the following chain structure and without password encoding.

-----BEGIN CERTIFICATE-----
(certificate: eg. your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: eg. DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: eg. TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: eg. your_domain_name.key)
-----END RSA PRIVATE KEY-----

If you have problems generating the complete and correct certificate chain, you can use tools such as https://whatsmychaincert.com/ as an aid.
'''Please keep in mind that you never give away the private part of your key.'''

=== Known issues ===
*The app platform webserver can use only the default http/https ports 80/443.
*By design, there is no possibility to restore the default webserver certificate on the App Platform, if another certificate was once uploaded. 
**If nevertheless needed, you must login with Putty (see [[#How to retrieve files from the AP| Retrieve files]]) and execute these commands as root:
**''psql -d manager -c "DELETE FROM config WHERE name='webserverCertificate'"''
**''/etc/init.d/S92manager restart''
*The app platform webserver interprets URLs case-sensitive. In other words, <nowiki>http://<addr>/file.txt</nowiki> is not the same as <nowiki>http://<addr>/FILE.TXT</nowiki>

== Database ==
The app platform creates a database for each app instance with a given password. In the installer there will be used randomly generated passwords. You can set a new database password for every instance in the Application Platform.

The apps should store all data in that database. That makes sure that a consistent backup and restore of app instances can be done by the app platform manager.
In hosted scenarios, having separate databases for each instance also makes sure that the data of different customers are clearly separated and can easily be moved from one physical platform to another.

The default configuration decline database request from extern. If you need external access you can change the PGSQL configuration (as root) in the file ''/mnt/sda2/pgsql/pg_hba.conf''.
After editing pg_hba.conf, the database-service has to be restarted with the command <code>/etc/init.d/S50postgresql restart</code>
(Please think about it before you do it, because a better way is to create your own local app with local database access.)

You can find the official documentation for the pg_hba.conf here: https://www.postgresql.org/docs/14/auth-pg-hba-conf.html

Please note that you do this on your own responsibility, that it makes sense to create a backup of the original pg_hba.conf
and that you may break your database server if you do not know exactly what you do!

Sometimes the Apps are not proper working after this. You can wait a while until everything is working again or you go the hard way:
* stop the manager
** <code>/etc/init.d/S92manager stop</code>
* restart the database-service (maybe not really necessary, but makes a good feeling)
**<code>/etc/init.d/S50postgresql restart</code>
* start the manager
** <code>/etc/init.d/S92manager start</code>

=== Nightly database analyse ===

Every database is analysed at night to keep indexes in sync with the data. This triggers a ''vacuumdb -a -z'', which updates optimizer statistics, but does '''not''' shrink the physical size of the database. 
This must be done manually in the instance settings.

== App Platform Manager ==
The App Platform Manager is the central component of the App Platform. It does the following:
* Installing app services by downloading the binaries from an app store.
* Running and monitoring app services. If an app service crashes it is restarted, automatically.
* Management of app instances and providing them with the environment they need:
** A database
** A webserver path
** A password for authentication
* Backup and restore of app instances.
* Collecting debug information like tracing and crash dumps.
* System monitoring (CPU usage, memory usage, etc).

== App Services ==
App services are runned by the App Platform Manager. They implement an interface that is used by the manager to start, stop and configure app instances. Each service runs in a separate child process of the manager.

== App Instances ==
The actual functionality of an app service is provided by app instances. They run in the same process as the app service but have a distinct webserver path and their own database. There can be 0..n instances of an app service. Instances can optionally host (web) apps that can be opened in the myApps client.

Each instance of an App service has two passwords. The instance password itself and a database password. If you want to change it you must update the password on both sides. 
The instance password must match to the password in the corresponding PBX App objects, while one instance can have different App objects. 
The database password must be just known to the manager and not outside of the App Platform.

The ''Database name'' and ''Database user'' are both limited to a length of 63 characters. By default, the App Manager would create ''<domain>''_''<instance-name>'' as value for both. This is why it is recommended to use instance names so that length(name) + length(domain) is less than 63 characters. However, if this is not possible, you can manually shorten the suggested values (both must still be unique on your App Platform).

=== Cleanup database ===
You can cleanup the instance database inside the instance settings. This starts the vacuumdb process for the instance database which frees disk space of deleted rows.
Note that this process locks the database and that sufficient disk space is needed to complete it!

=== External database host ===
You can optionally configure an external database host, if the database shall be hosted on an external host. 
Note that the App Platform Manager still creates a local database, which is then not used as long as the external host is configured.

What are external databases useful for?:
* User data is too large (files are stored as BLOB in the database)
* Other (non-innovaphone) database servers are to be used due to other regulations
* There is already an external database cluster with its own backup/restore processes which should be used
* More performance is required (please note that a local UNIX socket provides much faster results than a remote database server). Depending on the app and the task of the app, it can still be useful to use a separate server if it is faster.

==== Supported database types ====
In principle, ''PostgreSQL'' and ''MySQL'' are supported. However, please note that the respective app must be designed for the target database server type. If an app has been developed for PostgreSQL, it cannot be operated on a MySQL server.

'''Please note:''' All innovaphone apps are developed exclusively as PostgreSQL apps.

MySQL therefore only makes sense if own apps are developed and MySQL or certain MySQL features are to be used. For such apps, it is very important to deactivate the automatic Application Platform APP-Backup.
The database backup process of the App Platform uses PostgreSQL backup commands, which is why the backup would fail, so the app must be excluded from the backup, and you must take care of the backup yourself.

==== Database creation ====
If you use an external database, you have to create the database itself.
The App Platform Manager itself creates a PostgreSQL database like this (you may respect this on your database host to be compatible with the database implementation inside the Apps):
* CREATE DATABASE "dbname" ENCODING 'UTF8';
* CREATE USER "dbuser";
* ALTER USER "dbuser" WITH PASSWORD 'dbpassword';
* GRANT ALL PRIVILEGES ON DATABASE "dbname" TO "dbuser";
* ALTER DATABASE "dbname" OWNER TO "dbuser";
* REVOKE CONNECT ON DATABASE "dbname" FROM public;

==== Database connection ====
There are different possibilities to specify the host. You can use a DNS-Name, IPv4 or IPv6. A port can be optionally added with a colon.

Our PostgreSQL implementation sets sslmode=prefer, so SSL is used by default if enabled on the server.

==== Backup/Restore ====
External databases are still backuped as normal, but you can't restore such a database with the App Platform Manager on the external host! You must restore such a dump manually on your database host.

==== Database redundancy ====
In principle, it is possible to create redundancies for failure scenarios through this function.

However, there are different scenarios that need to be evaluated on a case-by-case basis:

* One database, multiple App Platforms (primary online / secondary '''offline''') where multiple apps access the same database.
** This mode of operation is legal as long as you can really ensure that only one App Platform is active at a time.

* One database, multiple App Platforms (primary online / secondary '''online''') with multiple apps accessing the same database.
** This operating mode cannot be used for innovaphone apps, as the app itself would have to be developed for such a mode, which it is not.

However, we advise great caution here! The use of the same databases from different nodes may only be used if you can ensure that the databases or runtime environments of apps cannot get into a ''split-brain'' mode.

== Relationship between app instances and app objects in the PBX ==
Typically an app instance is connected to one or more app objects in a customer PBX. This is done by configuring the same parameters on both sides:
* URL
* Password
The password is used by the PBX for authenticating itself, users and services against the app instance.

Some apps need a websocket connection with the PBX. When "websocket" is activated at the app object, the PBX establishes a websocket connection to the app instance and provides the APIs that are configured at the app object.

=== Supported scenarios ===
It is important to understand that the concept does not do any assumptions on how PBXes and APs are correlated. So you can have
* One App Platform for one customer
* One App Platform for many customers
* Many App Platforms for one customer
* Many App Platforms for many customers

Attention: The V13 installer can only configure the scenario "''One App Platform for one customer''". If you want to have a different scenario, you have to configure it manually.

For hosting or cloud scenarios you need special scenarios. Please refer our [[Howto:V13 Hosting| V13 Hosting]] instructions.

=== Restrictions ===
Currently we don't have redundancy for app instances or App Platforms.

== Update of the App Platform itself ==
The App Platform is build on top of buildroot and will receive updates and fixes from time to time. 
You can update the used build inside the Manager App by using the '''Update''' button at the top. 

It is strongly advised to make a full backup (VM) or at least backup all apps (Gateway) before you run such an update!

After the update has been downloaded and verified, your App Platform will reboot.
You can check the installation process after the reboot with the following URL: https://IP-of-AP/manager/ramdisk.log

== App services and multi-threading ==
Each App Service runs in a single process with no multi-threading, independent of the instances of the App Service. However, each instance maintains its own database connection and the database responds to this connect with the creation of a new process. Each app service therefore uses 1+''n'' threads (where ''n'' is the number of instances). All communication between app service instances and their clients must pass the single-threaded web server. On platforms with multi-threading support (i.e. VMware or Hyper-V), up to 1 + ''m'' + ''m'' * ''n'' (with ''m'' being the number of Apps and ''n'' the number of instances per App) threads can be utilized.

= AP Manager settings =

== General ==
* ''Enable Developer mode'': in developer mode, apps can be manually uploaded without an App Store
* ''Disable App security'': each App has an own unix user and if this flag is set, the user can login with SSH for debugging
* ''App Store URL'': the URL to the App Store where Apps are searched and also an update of the AP image itself
* ''Devices app URL'': the URL to the Devices App to manage the AP through Devices
* ''Devices app URL 2'': don't use!
* ''App Platform DNS name'': currently not used
* ''NTP server 1/2'': NTP servers for this AP (in addition to NTP servers retrieved by DHCP)
* ''Timezone string'': A timezone string which is used by the App Platform Manager to do certain jobs according to the configured timezone.
** Note that this doesn't change the timezone of the linux itself!
* ''DNS server 1/2'': DNS servers for this AP (in addition to DNS servers retrieved by DHCP)
* ''Database optimization time'': The database optimization process will be started at this hour (local time), with a random offset of up to 7 hours
* ''Command file'': see [[#Backup_of_the_Apps| Backup of Apps]]

== Security ==
* ''Current Webserver certificates'': shows the current certificates with the ability to download them.
* ''Webserver certificate'': upload a webserver certificate in PEM format
* ''AP Manager password'': the password to the web interface of the AP Manager (normally set through Devices)
* ''Linux root user'': password of the root user (normally set through Devices)
* ''Linux admin user'': password of the admin user (normally set through Devices)

== Let's Encrypt ==

Configure the certificate creation by Let's Encrypt here.

* ''Enable'': turns the automatic creation on or off
* ''Let's Encrypt App URL'': the URL of your Connector for Let's Encrypt App Service. You can copy&paste this URL from your Connector for Let's Encrypt PBX Manager Plugin
* ''Let's Encrypt App Password'': the client password of your Connector for Let's Encrypt App Service. You can copy&paste this password from your Connector for Let's Encrypt PBX Manager Plugin
* ''Key length'': 2048, 3072 or 4096 (keep in mind, that [[{{NAMESPACE}}:Certificate_management#Certificate_Key_Length_and_CPU_Usage|a higher value provides higher security but also lower performance!]])
* ''DNS Name'': the external DNS names of your device (up to 100 possible)

== Alarms and events ==
* ''URL'': URL to the Events app
* ''Username/Password'': HTTP credentials of the Events app
* ''Email address'': an email address which will get emails on full disk alarms/warnings
* ''Threshold'': All Apps will be stopped and an hourly email sent on reaching this threshold. An alarm is generated 10% before reaching this threshold and an email is sent every 24 hours.

== SMTP ==
SMTP server settings for sending emails from within the AP Manager.

Starting with 16r1 you also can configure OAuth2 Authentications. You can have a look into our HowTo Article for assistance: [[Howto16r1:Configure OAuth2 E-Mail]]

== Replication ==
App Platform [[#App Platform replication|replication settings]]

== Registered Access Domains ==

== Update ==
Updates the App Platform to the latest image available on the App Store.

== Restart ==
Restarts the App Platform.

== Shutdown ==
Shuts down the App Platform.

= App Platform replication =

== Requirements ==

* 13r3 or above on both standby servers and the primary server
* at least an App Platform image starting with version 110002 (otherwise postgresql is too old)
* standby and primary servers must have the same system architecture
** arm gateways (IPx11) just with arm gateways (IPx11)
** arm64 gateways (IPx13) just with arm64 gateways (IPx13)
** x86_64 virtual machines just with x86_64 virtual machines
* the disk size on standby servers must be at least equal as the disk size on the primary server

== General ==
The configuration is done within the App Platform Manager next to the settings button under "Replication".

=== Off ===
No replication is done at all.

=== Primary ===
The App Platform acts as primary server for one or multiple standby servers. 
Max 8 standby servers can be configured. 
 
Every standby server must get a unique name on the primary server which is then also configured on the standby server itself. This is due to the fact, that the primary server preserves data for every standby server while it's not reachable. 
A standby server name must be a valid domain name, although this name is currently not used as DNS name (but might be used in the future). 
 
The password is randomly pregenerated and must be used as handed by the App Platform Manager.

==== PostgreSQL port ====
The default PostgreSQL port is 5432 and can't be changed on the primary. It must be reachable through your firewall or at least forwarded on a different port towards this App Platform on port 5432.

=== Standby ===
Configure the password from the primary and one of the not yet used standby server names. 
The host and port must be reachable through the network. You can specify a non default port which then must be forwarded somewhere else to port 5432 on your primary.

*Note: Do '''not''' configure the same standby name on different standby servers, as this will break the replication on at least one standby! 
*Note: On a standby, all '''locally installed apps are removed''' during installation

== Failure detection ==

The replication state on both primary and standby servers are continuously monitored. 
In case of a broken connection, an alarm is triggered at once and just cleared if the failure goes away. 
 
If such an alarm lasts for 5 minutes an email is send. The recipient address must be configured in the App Platform Manager settings under "Alarms and Events" and you must also provide a valid SMTP configuration.

== Failover ==

There is no automatic failover procedure. If you detect the failure state, you must get active yourself.

=== Standby down ===

Fix the standby server and see if the replication comes up again. If not, setup a new standby server which will replicate the whole database cluster from scratch.

=== Primary down ===

If the primary is down and cannot be brought into life again, you must take the following steps, depending on your configuration:

==== One standby server ====

* Disable the replication in the replication configuration. You will then have a standalone App Platform afterwards.

==== Multiple standby servers ====

* Change the replication type on one of the standby servers from standby to primary. Please note that the other standby entries must still exist here (they are automatically offered)!
* Change the host entry on the other standby servers to the new standby server. The standby server will sync the whole database cluster again, which will take time.

==== Configuration changes ====

You must also tell the PBXes and other tools to use the new primary server.

* You may simply change the IP address behind the DNS of your primary server to point to the new primary server.
**Note: to ensure rapid recognition of the new DNS target, the definition of an appropriate TTL value is recommended
* Without DNS, you must currently modify the configuration by replacing the IP address of the old primary with the new address.
** This must be done in every master PBX configuration.
** This must be done in every App configuration which may use this IP address, e.g. Devices which rolls out an alarm server configuration

== App Platfom update ==

If you're running an active standby server and the major version of the PostgreSQL database didn't change, you can simply update primary and standby servers independently. 
 
If it contains a ''new major version'' of the PostgreSQL database, you must follow these steps:

* deactivate replication on all standby servers (which promotes these standby servers to active servers)
* ensure that the '''same''' App Platform Manager version is running on primary and standby servers!
* perform the App Platform update on the primary server
* perform the App Platform update on the standby servers
* reactivate replication on the standby servers (which will do a full replication again, so it might take some time)

Alternativly you may setup the standby server from scratch directly with the new App Platform image version.

Sadly there is currently no better method offered by PostgreSQL to perform such an upgrade.

See also https://wiki.innovaphone.com/index.php?title=Howto14r2:Firmware_Upgrade_V14r1_V14r2#App_Platform_and_Apps

== Technical backgrounds ==

=== Streaming replication ===

We use the asynchronous [https://www.postgresql.org/docs/9.3/warm-standby.html#STREAMING-REPLICATION streaming replication of PostgreSQL]. A transaction thus just waits for a commit on the primary server. Standby servers will receive the transaction asynchronously afterwards to avoid a reduced writing performance. 
A primary server keeps the neccessary WAL files for every standby server until the standby fetched the neccessary information. 
This fact can lead to higher disk space usage on the primary if one or multiple standby servers are offline for a while.

Take care to fix broken replications as soon as possible to avoid a full disk on the primary server!

=== What is replicated ===
The whole database cluster of an app platform is replicated. This includes every database of every instance and the database of the App Platform Manager itself. 

=== App Services on standbys ===
The database of the App Platform Manager itself also contains the App service binaries to be able to restore applications in a failover case. 
You do not have to install App services on the standby if you install them on the primary. 
App Platform Manager and Webserver can be updated as usual through the App Store or the Devices App if the standby is connected to Devices.

=== App Platform Manager configuration of the standby server ===
The App Platform Manager configuration of the standby server cannot be stored inside the database, as the database is readonly. So it is stored inside a configuration JSON file under ''/home/root/standby.conf''. 
This configuration is backed up as usual by a Devices backup job and can be also manually restored on a standby (not on a primary though!).

Configuration options from the primary are not synced to the standby server, as the standby server has its own configuration (as it could be in a different network etc.)!

=== No automatic failover ===

There is currently no automatic failover mechanism. PostgreSQL doesn't offer multi master replication, so writing is just possible on the primary itself. Standby servers have a readonly database. 
Let's consider the following use case if we would implement an automatic failover with the current technical possibilities: 
* The primary server is connected to a master PBX.
* A slave PBX is also connected to the primary server in another location.
* A standby server is in this location and replicates from the primary.
* The internet connection between primary and standby fails.
* The standby promotes itself to primary, so that the master PBX now writes to the old primary and the slave PBX now writes to the "new" primary.
* The internet connection comes up again and both primary and standby servers now have databases which are out of sync and which cannot be merged.

=== Security ===

* port 5432 must be reachable on the App Platform
* For every standby a PostgreSQL user is created with the REPLICATION role on the primary. Just this user has access to the database server from non localhost connections.
* You cannot establish a standard connection with such a user and modify/read from tables.
* The replication connection is established over TLS by default.

= App Installer PBX Manager Plugin =
== Requirements ==

* V14 and above

== General ==

The app installer plugin allows IT administrator (with access to the PBX Manager) to install/update/delete new apps from the innovaphone app store including Partners apps. It is automatically available with existing app platforms or after adding a new one in the PBX Manager.
It offers a view to the App Platform Manager‘s App Store with all the available functionalities and simplifies the install, update and uninstall of apps.

== Dedicated AP for each user ==

Installing a new app will install the app service and add a new instance with the user’s domain. The instance is automatically started. 
This further enables the configuration of the instance through its respective PBX Manager plugin. 
Uninstalling the app will remove the app service and the corresponding instance.

== Shared AP between users ==

Installing a new app works in a similar way to that of the dedicated AP. However, each time a new user installs the app, only a new instance is created if the app service is already installed. 
A user can uninstall the app, in this case the corresponding instance is deleted. If no more instances exist, then the app service is uninstalled. 
The administrator can only update the app service in such scenario.

= Known Issues =

== Reboot after an image update hangs (ARM gateway) ==

If it happens, that the App Platform doesn't recover after the reboot, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
If '''Kernel command line''' is set to '''/dev/ram0''', the App Platform booted the ramdisk. 
 
Try to fetch the upgrade log file:
https://[APP-PLATFROM-IP/DNS]/manager/ramdisk.log
 
If this doesn't work, try to login with putty in this case (default credentials admin/ipapps and root/iplinux) and issue this command: 
''cat /apps/install_step1.log'' 
 
If this file contains '''finished''' at the end, you can reconfigure the settings under App Platform -> General: 
* press '''Stop'''
* Initrd file: empty
* Kernel command line: '''root=/dev/sda3'''
* Ramdisk size: empty
* press '''Start'''

The App Platform should boot and run the already updated image.

<pre style="color: red; font-size:150%;">---WARNING---
If the file doesn't contain "finished" at the end, you may still need to wait, as an upgrade may take some time!
Do not reconfigure without being sure that the upgrade has finished, otherwise your system may won't run!</pre>

== Reboot after an image update boots always into rescue mode (virtual machine) ==

This most likely means that the image installation didn't finish the first time and was interrupted before the bootloader settings could be changed back to the default partition. 
 
If your App Platform doesn't boot or isn't normally accessible after manual selection of the standard entry in the boot menu, you need to '''revert''' to a '''snapshot/backup''' prior to the update. 
If your App Platform runs normally though, you can follow this instruction to change the default boot entry: 
 
* boot into the '''rescue''' partition
* login with root/iplinux
* edit the file /boot/grub/grub.cfg
** search the line with '''set default=0''' and change it to '''set default=1'''
** reboot

== App Platform doesn't start after an update ==

=== Gateway ===
If it happens, that the App Platform doesn't want to start an update, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
* '''Shutdown''' the App Platform and '''Stop''' it 
* Set '''Kernel command line''' to '''/dev/ram0''' 
* Set '''Initrd file''' to '''ramdisk.ext2.xz''' 
* Set '''Ramdisk size''' to '''100000''' 
* '''Start''' the App Platform now. 

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

Note: This process can take a while, after it's finished it reboots and automatically change the '''Kernel command line''' value.

=== Virtual Machine ===

Boot into the '''rescue''' partition.

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

=== It still doesn't start ===

If it still doesn't start, configure the App Platform to boot from /dev/sda3 (or inside a VM start the second boot loader entry) and login with SSH as root.
Then do a first check to verify that you have a specific error due to an incomplete update or a [[Howto15r1:Firmware Upgrade V14r2 V15r1#AP Upgrade to Image 130006|wrong update order]]:

* /etc/init.d/S92manager stop
* /apps/manager/manager
* if this outputs '''error while loading shared libraries: libcrypto.so.3:''' you have a manager version which cannot run on the current image.

In this case you must download an older build (14r1 1410593):

* /etc/init.d/S92manager stop
* wget --no-check-certificate -O /apps/manager/manager https://webbuild.innovaphone.com/1410593/arm/manager/manager
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* wget --no-check-certificate -O /apps/webserver/webserver https://webbuild.innovaphone.com/1410593/arm/webserver/webserver
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* chown root:root /apps/manager/manager
* chown root:root /apps/webserver/webserver
* chmod +x /apps/manager/manager
* chmod +x /apps/webserver/webserver
* echo 110000 > /mnt/sda1/label
** this allows the manager to perform an image update again
* /etc/init.d/S92manager start
* now perform an image update and '''afterwards''' update your apps again

== Webserver doesn't respond after an image update ==

If you can't reach the web UI after an image update, please try to connect with SSH as admin user and delete old coredumps, which may prevent the App Platform Manager from starting correctly:
* su root (become root)
* rm -f /mnt/sda2/log/core_dumps/*/*
* /etc/init.d/S92manager restart

Check if you can now reach the App Platform again.

= Tracing =
Each App Service has its own log file, which can be accessed through the Manager App. You can configure a log file size for each App Service. 
Each App Intance has its own trace flags. The following trace flags can be set: 

* Alarm client: used by the manager to send alarms to an alarm server
* App: logs from the App Service itself
* App WebSocket: logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
* AppSharing: just native clients
* AppProxy: just native clients, logs requests which are proxied between the local webserver and the remote server
* Audio: just native clients
* Browser: just native clients
* Command: the command interface is used to execute shell commands, e.g. used by the manager App
* Config: logs config changes of an App
* Database: database logs
* DB files: database file logs
* DNS: DNS request logging
* DTLS: just native clients, DTLS request logging
* Ethernet: interface to get ethernet adapater infos, just manager App
* File: logs for file system access (synchronous), e.g. manager App
* Files: logs for file system access (asynchronous)
* HTTP client: http client logs
* HTTP file: logs for static HTTP files
* ICE: just native clients
* LDS: local domain sockets
* Media: just native clients
* Media channel: just native clients
* Process: IProcess interface logs which is used for spawning, killing processes etc.
* SMTP: SMTP client logs
* TCP: TCP logs
* Time: ITime interface logs
* TLS: TLS logs
* TURN: just native clients
* UDP: UDP logs
* Video: just native clients
* WebSocket client: logs outgoing websocket connections
* Webserver traffic: logs incoming HTTP traffic, which is forwarded from the webserver to the App
* WebDAV service: logs WebDAV requests to the App
* Webserver: enables webserver specific logs

== RPCAP ==

If you open the Manager App, click on the Manager in the left list and then on the Diagnostics button, you can enable RPCAP. 
You can add the interface in wireshark with the string:
rpcap://<APP-Platform-IP>/eth0

'''Please don't forget to disable RPCAP after your testing!'''

= How-Tos =

== How to retrieve files from the App Platform ==
To retrieve files from the App Platform which can not be retrieved via the App Platform manager UI, you can connect to the App Platform using the SCP protocol on port 22. 
 
First copy files to /home/admin as root with Putty or another SSH client:
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''su root'' to be root (''iplinux'' as default password)
 
You can now copy files to ''/home/admin'' (e.g. from /var/log/apps/manager/...). 
 
You can create a tar archive with all logs like this:
* cd /home/admin
* tar -cf - /var/log/* | xz -z - > log.tar.xz
** you may want to exclude coredumps (due to their size):
** tar -cf - --exclude=/var/log/core_dumps/* /var/log/* | xz -z - > log.tar.xz
* chown admin:admin /home/admin/log.tar.xz
 
Then copy the files to your local system, e.g. with WinSCP 
* use ''SCP'' as protocol (NB: WebDAV is not supported on most of the directories on the App Platform )
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''/home/admin'' as start directory
* copy the needed files

== App Platform disk space warning ==

If the configured threshold is reached, all Apps are stopped inside the App Platform . You must then free disk space somehow.

=== Find large instances ===
Click through your apps in the tree on the left side and take a look at the database size of each instance.

=== Delete data inside an instance ===
It depends on the type of app if you can delete data or not. E.g. you can start the Files app and delete files inside this app. 
This won't reclaim disk space though due to the way how PostgreSQL databases work, so you need to follow this guide to reclaim the disk space:

* start the corresponding App
* delete data inside the App
* optimize disk usage of the database by cliking on the button "Clean up database" under Edit instance. If this does not help, continue with the following steps.
* stop the corresponding App again
* download a backup of the instance (backup button at the top), this backup contains the whole instance data, also the password of the instance
* delete this specific instance
* restore the downloaded backup (restore button at the top)

Depending on the hardware and the size of the instance, this process may take hours to complete!

=== Resize the disk ===
The resizing of a disk is just possible for virtual machines, see [[#Resizing the disk of a Virtual machine|Resizing the disk of a Virtual machine]].

=== Delete the whole instance ===
If there is no other possibility, you can delete the whole instance. Afterwards you recreate the instance with the same values and a new random password. Don't forget to set this password in the corresponding PBX App objects though!

=== Restart the Apps or the App Platform ===
If you have enough disk space again, you must either restart the whole App Platform or you manually start all Apps again.

== App Platform/Apps app not online anymore due to full disk ==
If the apps app is not online anymore and you can't access any apps anymore, try to login with an SSH client to see if your disk is full.
Login as admin and afterwards as root (su root). 
 
* issue '''df -h''' and see the disk usage of /dev/sda2, if this is 100%, your disk is too full
* stop the manager
** /etc/init.d/S92manager stop
* empty the 500 MB file, which is exactly for this case here (manager must be 13r1 SR9 or higher to have this file)
** echo "" > /mnt/sda2/empty_if_no_space
* delete log files to recover some space
** rm /var/log/apps/*/*
** rm /var/log/core_dumps/*/*
* restart the postgresql server (see the output if this worked or not)
** /etc/init.d/S50postgresql restart
* restart the manager
** /etc/init.d/S92manager restart
* wait until everything is online again
* open the Apps app and try to find the instance which uses the most disk space and try to delete files/content from it
** you may want to stop all app services first to prevent more writes to the database
** if not possible, you can delete this instance, but you'll loose all data from this instance then!
* after that you can try [[{{NAMESPACE}}:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files|Reference14r2:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files]] to free up space
** If this does not work you can create a backup from the database, delete the database and import the database again.
* free up at least 500 MB so that the manager can create the file again
* delete /mnt/sda2/empty_if_no_space if you are done and restart the manager:
** rm /mnt/sda2/empty_if_no_space
** /etc/init.d/S92manager restart
** the manager restart automatically recreates the empty_if_no_space file if this file doesn't exist

Make sure, that you do '''not''' have backups configured to a local files instance while this files instance is not excluded from backups.
An instance can be excluded from backups in the instance settings in the App Platform Manager.

If all of this doesn't help, you can resize the file system on a VM:
* proceed with [[{{NAMESPACE}}:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine|Reference14r2:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine]]

== Resizing the disk of a Virtual machine ==

Do '''NOT''' resize if you're running an App Platform version higher than '''110000''' and lower than '''110027''' or '''130007''' and lower than '''130015''' or your data will be lost!
Please update your App Platform to version 130015 or higher before you start resizing your disk.

* stop the VM
* expand the disk using your VM utilities
* start the VM and boot from the first boot entry '''rescue/setup'''
* login with '''root''' and '''iplinux'''
* execute this command: '''/home/root/install_step1.sh log.txt resize'''
* the VM reboots automatically after a successful resize

== Shrink the physically size of PostgreSQL database files ==
Tuples that are deleted in your database are not physically removed from the database-file. So the claimed space on the harddisk is still in use after the delete operation.
If you need to free up some disk space you can force to reorganize the physically database-file on your harddisk.

You can also start this process through the instance settings as long as the App Platform Manager is still running.

'''Important: You are operating on the Database, you have to make a Backup of your Database before you do this!'''

Login via SSH to the APPlatform with the ''admin'' User
su root

=== All databases ===
/etc/init.d/S92manager stop # not always needed, but in case of database errors recommended, of course no app is online then
sudo -u postgres reindexdb -a
sudo -u postgres vacuumdb -a -f
/etc/init.d/S92manager restart # just execute if the manager has been stopped above

=== single database ===
sudo -u postgres reindexdb -d dbname # for a single database with dbname
sudo -u postgres vacuumdb -d dbname -f # for a single database with dbname

Note: This may take some time and the App database is not available during this time

After the process you can check the free dispace via <code>df -h</code>. You can check the claimed space from the database file with the command <code>du -sh /mnt/sda2/pgsql/</code>.

== Change IP Addresses / DNS Names / System Name ==

If you want to change the System Name or the DNS Name of the PBX and/or App Platform Platform you must change records manually '''in the described order'''!
You have to know the Admin password to directly Login to the App Platform .

=== App Platform ===
; Settings - General
* ''Devices app URL''
* ''App platform DNS name''

; Settings - Alarms and Events
* ''URL''

; All Instances
* ''Domain''
* ''Webserver path''

=== PBX ===
Download the configuration and ''search/replace'' in the config file. Upload the config file and reboot.

Manual:
* ''URL'' in all PBX Object (Apps, Voicemail ...)
* [[{{NAMESPACE}}:Gateway/CDR|CDRx]]
* [[{{NAMESPACE}}:PBX/Config/General|IP address for App Platform]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reset Password Page]]
* [[{{NAMESPACE}}:PBX/Config/Authentication|Verification link]]

Depending on your change you have to activate/deactivate the Setting [[{{NAMESPACE}}:PBX/Config/General|Operation without DNS]]

=== Additional Devices / Steps ===
* ''Devices Registration URL''
** There is no automatism to change the URL on all devices in your setup.
** If you have the option to use DHCP, you can temporarily overwrite the [[{{NAMESPACE}}:Services/Update|Update URL]] and execute a [[{{NAMESPACE}}:Concept_Update_Server|custom update script]] to change the ''Device Registration URL''
* ''Alarm server''
* Reverse Proxy configuration
* Change ''Domain Name'' in Devices if you have also changed the system name

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

initial error at 1500329378: ext4_journal_start_sb:328
last error at 1500329378: ext4_journal_start_sb:328

Or you get events like "Broken file system" from your App Platform .

This indicates a file system failure on the Linux Installation.

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

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

=== Gateway ===

* Open the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the Kernel command line from root=/dev/sda3 (or /dev/nvme0n1p3) to root=/dev/ram0
** modify the Initrd file to ramdisk.ext2.xz
** modify the ramdisk size to 100000
** start Linux again
:: This will run Linux on another (hopefully sane) partition.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code> on IPx10/IPx11 gateways
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code> on IPx10/IPx11 gateways
** on the command prompt, use <code>e2fsck -p -f /dev/nvme0n1p2</code> on IPx13 gateways
** on the command prompt, use <code>e2fsck -p -f /dev/nvme0n1p3</code> on IPx13 gateways
:: this should fix any issue on the file system

* go back to the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/ram0'' to <code>root=/dev/sda3</code> (IPx10/IPx11) or to <code>root=/dev/nvme0n1p3</code> (IPx13)
** clear the Initrd file field
** clear the ramdisk size field
** start Linux again
:: This will run Linux on the original partition.

=== VM ===

Restart the VM and select the first entry in the boot menu from grub.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system
* Reboot your VM
[[Category:Concept]]

== How to create a memory dump of a running process ==

Sometimes it's usefull to have a memory dump of a running process to investigate certain issues.

* login with SSH and become root
* find out the PID of the relevant process, e.g. with ''ps aux | grep /apps/manager/manager | grep -v grep''
* gdb --pid PID -ex gcore --batch
* this creates a core file core.PID
* download this core file with WinSCP or similar tools

== Move instance database to external database host ==

In case you want to use an external database server instead of the integrated:

* download a backup of the specific instance over the App Platform Manager
* create a postgresql database on the external host:
** createdb --encoding=UTF-8 exampledb
* restore the backup
** pg_restore -d exampledb backup-exampledb.dump
* change the ownership to a specific postgresql user (which you have to create yourself first)
** psql -d postgres -c "ALTER DATABASE exampledb OWNER TO exampleuser"
* configure the database host, name, user and password on the instance inside the App Platform Manager

Reference16r1:Concept App Service IP

2026-03-16T06:43:46Z

Dde: /* Configuration */

[[Category:Concept|Apps]]
[[Category:Concept|IP]]

The App IP is an app which offers the PBX functionality and further functionalities as App service on our innovaphone App Platform.

== Applies To ==

* innovaphone firmware and apps V16

==Requirements==
* innovaphone Application Platform (image version 140011 or higher)

==Concept==

The App IP offers modules known from innovaphone gateways, like the PBX, TURN server functionality etc.

==How it works==

=== Single instance mode ===
Unlike other App Services, the App IP is a single instance App Service, so you can create '''just''' a single instance and not multiple instances.

== Licensing ==
Standard licensing mechanisms apply to the App IP as they apply to innovaphone gateways.

In addition, every port license requires a dedicated IPAP license (similar to the IPVA license for virtual machines).

== Apps ==

There is no App provided by this App Service.

== PBX Manager Plugins ==

There is no PBX Manager Plugin provided by this App Service.

== Configuration ==

The configuration is done as an innovaphone gateway is configured too.

=== Advanced UI ===
The advanced UI is reachable under the webserver path of the App IP instance and /admin.xml?xsl=admin.xsl, e.g.:
https://domain.com/ip/admin.xml?xsl=admin.xsl

=== IP configuration ===
As the App IP is just an App on an App Platform, there are no IP4/IP6, NTP etc. settings as on other innovaphone devices.

==== Devices App ====
If your App Platform which runs the App IP is connected to a Devices App, you can access the Advanced UI with the '''PBX''' tab of your App Platform device.

==Troubleshooting==

The App IP offers standard tracing mechanism for App Services and in addition mechanisms known from innovaphone gateways. 
You can enable module related trace flags with config change commands or by setting trace flags under Maintenance -> Tracing in the Advanced UI of the App IP.

Trace files are not found under Maintenance -> Tracing but on the App IP service on your App Platform Manager.

==Known issues==

==Related Articles==
* [[Reference16r1:Concept_innovaphone_App_Platform_Docker_Container]]

Reference16r1:Concept App Service IP

2026-03-16T06:43:27Z

Dde: /* Configuration */

[[Category:Concept|Apps]]
[[Category:Concept|IP]]

The App IP is an app which offers the PBX functionality and further functionalities as App service on our innovaphone App Platform.

== Applies To ==

* innovaphone firmware and apps V16

==Requirements==
* innovaphone Application Platform (image version 140011 or higher)

==Concept==

The App IP offers modules known from innovaphone gateways, like the PBX, TURN server functionality etc.

==How it works==

=== Single instance mode ===
Unlike other App Services, the App IP is a single instance App Service, so you can create '''just''' a single instance and not multiple instances.

== Licensing ==
Standard licensing mechanisms apply to the App IP as they apply to innovaphone gateways.

In addition, every port license requires a dedicated IPAP license (similar to the IPVA license for virtual machines).

== Apps ==

There is no App provided by this App Service.

== PBX Manager Plugins ==

There is no PBX Manager Plugin provided by this App Service.

== Configuration ==

The configuration is done as an innovaphone gateway is configured too.

=== IP configuration ===
As the App IP is just an App on an App Platform, there are no IP4/IP6, NTP etc. settings as on other innovaphone devices.

=== Advanced UI ===
The advanced UI is reachable under the webserver path of the App IP instance and /admin.xml?xsl=admin.xsl, e.g.:
https://domain.com/ip/admin.xml?xsl=admin.xsl

==== Devices App ====
If your App Platform which runs the App IP is connected to a Devices App, you can access the Advanced UI with the '''PBX''' tab of your App Platform device.

==Troubleshooting==

The App IP offers standard tracing mechanism for App Services and in addition mechanisms known from innovaphone gateways. 
You can enable module related trace flags with config change commands or by setting trace flags under Maintenance -> Tracing in the Advanced UI of the App IP.

Trace files are not found under Maintenance -> Tracing but on the App IP service on your App Platform Manager.

==Known issues==

==Related Articles==
* [[Reference16r1:Concept_innovaphone_App_Platform_Docker_Container]]

Reference16r1:Concept App Service IP

2026-03-09T13:52:21Z

Dde:

[[Category:Concept|Apps]]
[[Category:Concept|IP]]

The App IP is an app which offers the PBX functionality and further functionalities as App service on our innovaphone App Platform.

== Applies To ==

* innovaphone firmware and apps V16

==Requirements==
* innovaphone Application Platform (image version 140011 or higher)

==Concept==

The App IP offers modules known from innovaphone gateways, like the PBX, TURN server functionality etc.

==How it works==

=== Single instance mode ===
Unlike other App Services, the App IP is a single instance App Service, so you can create '''just''' a single instance and not multiple instances.

== Licensing ==
Standard licensing mechanisms apply to the App IP as they apply to innovaphone gateways.

In addition, every port license requires a dedicated IPAP license (similar to the IPVA license for virtual machines).

== Apps ==

There is no App provided by this App Service.

== PBX Manager Plugins ==

There is no PBX Manager Plugin provided by this App Service.

== Configuration ==

The configuration is done as an innovaphone gateway is configured too.

=== Advanced UI ===
The advanced UI is reachable under the webserver path of the App IP instance and /admin.xml?xsl=admin.xsl, e.g.:
https://domain.com/ip/admin.xml?xsl=admin.xsl

==== Devices App ====
If your App Platform which runs the App IP is connected to a Devices App, you can access the Advanced UI with the '''PBX''' tab of your App Platform device.

==Troubleshooting==

The App IP offers standard tracing mechanism for App Services and in addition mechanisms known from innovaphone gateways. 
You can enable module related trace flags with config change commands or by setting trace flags under Maintenance -> Tracing in the Advanced UI of the App IP.

Trace files are not found under Maintenance -> Tracing but on the App IP service on your App Platform Manager.

==Known issues==

==Related Articles==
* [[Reference16r1:Concept_innovaphone_App_Platform_Docker_Container]]

Reference16r1:General/IP4/General/NAT

2026-03-06T11:00:34Z

Dde: Redirected page to Reference13r3:IP4/NAT/General

#REDIRECT [[Reference13r3:IP4/NAT/General]]

Reference16r1:General/IP4/General/STUN

2026-03-06T10:58:07Z

Dde: Changed redirect target from Reference16r1:IP4/General/STUN to Reference13r3:IP4/General/STUN

#REDIRECT [[Reference13r3:IP4/General/STUN]]

Reference16r1:General/IP4/General/STUN

2026-03-06T10:57:58Z

Dde: Redirected page to Reference16r1:IP4/General/STUN

#REDIRECT [[Reference16r1:IP4/General/STUN]]

Reference16r1:General/IP4/General/STUN

2026-03-06T10:55:41Z

Dde: Removed redirect to IP4/General/STUN

#REDIRECT [[{{NAMESPACE}}:IP4/General/STUN]]

Reference16r1:General/IP4/General/STUN

2026-03-06T10:54:33Z

Dde: Changed redirect target from Reference:IP4/General/STUN to IP4/General/STUN

#REDIRECT [[:IP4/General/STUN]]

Reference16r1:General/IP4/General/STUN

2026-03-06T10:54:08Z

Dde: Redirected page to Reference:IP4/General/STUN

#REDIRECT [[Reference:IP4/General/STUN]]

Reference:My Innovaphone

2026-03-02T13:20:10Z

Dde: /* IPVA MAC exists */

==Where is my old my.innovaphone?==
Don't worry, just login with your old my.innovaphone account! You will be asked to confirm your forename and surname (just a '''natural person''' is allowed) and accept some terms and conditions. 
Afterwards you find the old license/device view inside the [[#Licenses tab| Licenses tab]].

==About==
my.innovaphone allows the handling of licenses and includes the handling of device warranty and software service agreements. 
You can also sign contracts here for different purposes.

===Project-View===
My innovaphone offers the possibility for several users to be in one company. This company shares its balance of licenses over all users and can have several projects. Projects have their own balance of license types and devices are bound to a project.

===Language===
My innovaphone will support multiple languages. You can select your desired language at the top of the page. 
Currently supported languages:
* English
* German
* Italian
* Dutch
* French
* Spanish (partially)
* Polish (partially)

===Guides===

====Quickstart guide====
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_nl.pdf Dutch quickstart guide] 
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_en.pdf English quickstart guide] 
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_fr.pdf French quickstart guide] 
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_de.pdf German quickstart guide] 
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_it.pdf Italian quickstart guide] 

====SSA guide====
;V10 and greater:
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10nl.pdf Dutch SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10en.pdf English SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10fr.pdf French SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10de.pdf German SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10it.pdf Italian SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10pl.pdf Polish SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10es.pdf Spanish SSA guide] 

;V8 and greater:
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_en.pdf English SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_fr.pdf French SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_de.pdf German SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_it.pdf Italian SSA guide] 

==First steps==
Open [https://my.innovaphone.com my.innovaphone.com] and click the "I would like to create a new personal user account" link.
Enter your personal data and register.

You will receive a registration email with an activation link.
After account activation you have two options:
* create a new my.innovaphone company with the "Create company account" button
* ask another user of your company to invite your email address to an already existing company

If you accidentally created an own my innovaphone company, just ask another user of your company to import your just created company.

If you create a new company, you can '''optionally''' enter your innovaphone account ID (which is your customer number with innovaphone) with your postal code, to retrieve your company data.

Inside the license tab of the my.innovaphone portal, you will see a help link at the right side of the horizontal tab menu.
This link shows the corresponding text of the wiki section, when hovering with the mouse over it,
and redirects to the corresponding wiki menu, if clicked.

It is possible, that one user is member of serveral companies!

==Left bar==
If you open the left bar, you have the options to:
* select one of your companies
* edit your personal user account
** user name
** email address
** flag to recieve SSA expiry emails
** password
* create a new company
[[Image:Myinnovaphone bar.png|center|thumb|200px|myinnovaphone_bar.png/|myinnovaphone_bar.png/]]

==Main tabs==
Inside each company you see the three main tabs:
* Contracts
* Authorized persons
* Licenses (see [[#Licenses tab| Licenses tab]])

You may also have two buttons:
* Add Contract (just as company administrator or with the contract right)
* Invite person (just as company administrator)

[[Image:Myinnovaphone main.png|center|thumb|200px|myinnovaphone_main.png/|myinnovaphone_main.png/]]

=== Contracts ===
Inside the contracts tab, you see all your contracts and you can download these conracts. 
In general, contracts must be first approved by innovaphone, so you see three types of contracts:

* open contracts which must be approved by innovaphone first
* approved contracts which can be already used
* cancelled contracts which are not valid anymore

[[Image:Myinnovaphone contracts.png|center|thumb|200px|myinnovaphone_contracts.png/|myinnovaphone_contracts.png/]]

These type of contracts currently exist:
==== innovaphone myApps Cloud Service ====
Conclude this contract to use the innovaphone myApps Cloud.

==== innovaphone software rental ====
Conclude this contract to rent innovaphone software products. You must conclude this contract if you want to use the software rental inside the Devices App.

=== Authorized persons ===
Here you see all persons which exist inside your company. Each person can have the following rights:
* Administrator (everything)
* Contracts (can conclude contracts)
* Licenses (can work with licenses)
* Viewer (can just see everything without doing something)
* Locked (cannot even login to this company anymore)

=== Licenses ===
Here comes the old my.innovaphone view which allows the handling of devices, licenses, activation keys etc.

==Search (inside licenses tab)==
At the right top of the licenses tab you have a search field. You can search for different things:
* Devices (part of a device name or device comment)
* Projects (part of a project name or project description)
* Own activation keys (part of an activation key or its description)
* Hardware rental orders (part of the innovaphone order number or your own order reference or a MAC address of an order)

You have to enter at least '''three''' chars to start a search. To search for activation keys,
you have to enter at least '''five''' chars.
* Search for license types. Enter e.g. "PBX-Port8" to find all devices with Port8 licenses or enter "PBX-Port8=100" to find all devices with Port8 licenses '''>=''' 100.
* Search for products, e.g. 01-00811 für IP811 (such a search may take longer!)

==Licenses tab==
===Projects===
After creation of an own company, you will have a default project named "DEFAULT". You can rename this project later.
You can also create more projects on the projects page with "Create".
Each project of a company must have a unique name.

Do '''not''' set SSA, if you want to import your devices from your old license manager account first.
If you want SSA and you '''won't import''' devices into this project from your old account, you should set SSA at once.

You can select a certain project by activating it in the project list. This selection is then true for all other pages, as some pages require a selected project.

[[Image:overview.jpg|center|thumb|200px|overview.jpg/|overview.jpg/]]

By activating a project by clicking on the project name in the project list, you can manage this project and its settings.

==== Rental project ====
You can also manually create a rental project. A rental project is normally created automatically by uploading an activation key inside the Devices App. 
But if you want to start directly with an Automatic iSC reloading service, you'll need to create the project manually. 
Take care that the name '''equals''' the domain name in your Devices App. 
 
If the rental tab in your Devices App domain doesn't show the expected balance/Automatic iSC reloading contract/licenses etc., you may use the Devices App Guid Link mechanism to link the domain to this specific project (see below) (use Devices App '''13r3 SR12''' or higher!).

====Properties====
Rename the project or/and change its description. 
 
You can configure further CC mail addresses inside your '''License Purchase''' project, if you have one. If you purchase licenses on credit, the emails will be also sent to theses addresses.
 
 
Since version 10, an innovaphone device will automatically connect to http://config.innovaphone.com/init
This script looks at the project properties of the project, where the device exists. 
You can configure an update '''URL''' and a '''trusted certificate'''. 
 
;Devices App GUID link: This is a GUID which can be entered in the settings of a domain inside the Devices App to link the domain to this specific project, if the names do not match and/or the Devices App has been setup from scratch. The Devices App must use the customer to which this projects belongs to be able to use this GUID.

====Software Service====
You can put your project under SSA (software service agreement).
You will be asked to enter a SSA end date. This will be the date, where all SSA licenses of all devices in this project will expire.
The end date mustn't be more than one year in the past. 
Optionally you can enter a maximum SSC amount. The SSA end date will be automatically calculated then. 
If you have entered a maximum SSC amount, you have to use the '''Recalculate''' link to calculate a new SSA end date,
if you change your license selection.
 
You can also calculate SSA over all projects at once. In this mode, you '''won't be able''' to confirm the calculation. You'll just see the necessary SSC amount.

After entering a date/SSC amount, you will get a summary of all licenses, which will be put under SSA and the amount of needed SSC licenses.
The SSC value for each license is calculated by the bind date of the license and the entered SSA end date/SSC amount.

[[Image:Ssa_extend.jpg|center|thumb|200px|ssa_extend.jpg/|ssa_extend.jpg/]]

If you have licenses for an older version than the current version, you have to pay SSCs from the [[#Release dates|release date]] of the next version of the current license version. 

e.g. you have a V7 PBX-PBX7#15 license with bind date 1/1/2010. Version 8 was released on 7/12/2009, so SSA is
calculated from 7/12/2009 for this license. You will see the calculation date in the list under "bind date"

If licenses already have a SSA date, just the difference between the current SSA date and the entered SSA end date must be paid.
If the bind date of the device lies in the past, the difference between the bind date and the current date must be paided twice (this is the column 'days*2'). 
If your license is under SSA, which is already over, you also have to pay the time between the old SSA date and the current SSA end date twice.

Here is a short example, how the days are calculated:

Bind date: 24/06/2009 
Current date: 31/08/2009 
SSA end date: 12/12/2011 
 
You will have to pay from 24/06/2009 to 31/08/2009 twice for 68 days.
From 31/08/2009 to 12/12/2011 you will then have to pay the normal price for 833 days.

You can also select for each license, if you want SSA for it or not. If not, no SSC is needed and no (new) SSA end date is set for this license. 

You can preview the SSC calculation for another calculation date. Simply change the dropdown
selection to get the new SSC value.
Of course you can't confirm this calculation for another date, just for the current date!

''You may add additional licenses to the calculation, which you will bind later''. Just click on the '''+''' near this text and you can add
multiple licenses, which will be added to your calculation after using the recalc link. Listed are licenses of the current version and from
your balance.

After confirming your entered SSA end date, each license will have this date as SSA end date and can be downloaded in all versions of this SSA time.

You can now extend the projects SSA end date like as setting a new one.
The resulting summary is the same as above.

If your user account has the right to buy licenses on credit, just check the checkbox.
You may enter an order number, which you can use for your order, if you buy on credit.

=====Past SSA end date=====

You can configure a new SSA end date in the past, if you accidentally configured a wrong date. 
No licenses will be changed, if you configure a date in the past, just the SSA end date of the project!

=====SSA Expiry Mail=====

If project SSA will expire, each company user will receive a reminder mail '''7''' weeks before and
then every week one mail.
You can disable these mails with the checkbox 'Send SSA expiry mails'.
Note that every user can configure, if he wants to receive mails or not in his account settings.

If you want the end user of the project to receive an expiry mail, you can configure a '''reseller''' mail address and end user mail addresses. These end users will then receive an email, 30 days before the project will expire. The default text is:

Your Software Service Agreement for your innovaphone PBX in project "{$arg[3]}" will expire in {$arg[1]} days.
Please contact your reseller {$arg[2]} to upgrade the license. 
The upgrade of the license is important to secure the phone system!

You can change this text as you want. You can use placeholders:
* '''{$arg[1]}''': days left
* '''{$arg[2]}''': reseller mail address
* '''{$arg[3]}''': project name
 
You can also define a global text for all projects under your [[#Company| Company settings]].

You can optionally configure to receive project SSA independent reminder mails for each license of a device [[#Company 2|here]].

=====Automatic SSA Extension Service=====

You can request an automatic SSA extension service for a project, which is under SSA. By following this link, you will have the opportunity to request a callback and/or the necessary agreement as PDF file.

All licenses have to be under SSA to use the automatic SSA extension service!

There are some basics to know, if a project is under automatic SSA:
* If you bind new/free licenses, they'll get SSA until the current project SSA date and you will receive an invoice for the SSCs
* If you move devices into this project, their licenses will get SSA until the current project SSA date and you will receive an invoice for the SSCs
* You can't join this project into another project, but you can join another project into this one

====Rights====
=====Own project=====
Add or delete company rights for this project. To add a company right, you have to enter the company id of this company.
Each user of a company with rights on this project can add devices, licenses, activation keys to this specific project, but is restricted in removing devices, editing the project and can't create activation keys with the projects balance.

The company id can be found under Licenses->company and the company tab.

[[Image:Project_rights.jpg|center|thumb|200px|project_rights.jpg/|project_rights.jpg/]]

=====External Project=====
If another company granted access rights to a project to you, you can unsubscribe from this project here.

====Import====
The import has been disabled. All old devices are already imported and can be added to your project manually.

====Join====
Here you can join your currently selected project with another project, which you select from a dropdown box. 
If the other project has SSA, you'll see the current SSA end date, which you might change for the join process and you will get a list of all licenses, which might be updated to the ssa end date/changed date of the other project. The list equals the list shown under [[#Software Service|Software Service]].

The selected project will be automatically deleted after the join. You can't join a project,
if it grants external rights to another customer. Delete these rights before.

You can't change the SSA end date, if the other project is under automatic SSA! You will receive an invoice for SSCs used for the join.

====Project Move (admin only)====
A company admin can move a project with its devices, activation keys, balance etc. to another company. You have to know the company ID from this company, which can be found under Licenses->Company and the company tab. 
The history won't be moved!

Projects with negative balances can't be moved!

Existing project rights will be deleted.

====Delete====
Delete the project. Only possible if it has no activation keys, project rights, devices or user rights.
 
You may [[#Join|join]] your project into another one, if you can't delete it.

====Project Freed_RMA_licenses====
If you see a project with this name in your project list, you had a RMA device with not yed moved licenses, which was shipped to innovaphone and reshipped to another customer. 
The licenses of such a device have been moved into the pool of free licenses of the project Freed_RMA_licenses, from where you can assign them to another device.

====Rental====
Projects starting and ending with the '''$''' sign in their name are rental projects. 
The name corresponds to the domain name of a Devices App installation. 
 
All software licensing and device management can be just done through the Devices App itself, see [[Reference13r1:Concept_App_Service_Devices#Rental_program_and_Payment_method]]. 
Just '''hardware licenses''' still need to be bound inside my.innovaphone currently and have to be downloaded there and uploaded on the device itself just as usual.

===Balance===
On the balance page you will see the balance of the currently selected project or the balance of all your projects together.
The balance is bound to your company and '''not''' to your user account. The balance is bound to a specific project, but can be shared for license creation or activation key creation if wished. 
Sharing the balance over several projects is not possible in external projects!

[[Image:Balancepage.jpg|center|thumb|200px|balancepage.jpg/|balancepage.jpg/]]

====Free licenses====

Here you see a list of all your free licenses. If you return licenses from one of your devices, the returned licenses are stored in your free licenses pool. You can assign these licenses to another device (see [[#Add licenses from free licenses|'Add licenses from free licenses']]).

[[Image:Balance_free_lics.jpg|center|thumb|200px|balance_free_lics.jpg/|balance_free_lics.jpg/]]

The bind date, SSA end date and the external key (like DECT-Multi-Cell-Ari) are stored for each license.

===Activations===

You'll see a list of all your bound activation keys with their licenses here.

[[Image:Activations.jpg|center|thumb|200px|activations.jpg/|activations.jpg/]]

====Add an activation key====
To increase your projects balance, select one of your projects, follow the "Add" link and enter the activation key in the corresponding field. You can also enter an optional comment for this key. You will then get a listing of all contained licenses. After commiting this key, your project balance will have been increased by the keys values.

"Deselect the current project" to view all activation keys independent of the selected project.

====Search for an activation key by your order number====
Enter your own order number (or nothing), to view your activation keys for this order.

====License certificate====
You can always download the innovaphone license certificate for activation keys in your projects. Simply press the download link in the list at the right side.

===Own Activations===
Here you'll see a list of all created activation keys in the selected project (or over all projects).

You can create activation keys on the project page for other users/companies or to simply transfer licenses from one project to another. 
You can enter a comment, an order number and an order reference. The '''order number''' is your own order number for the key and the '''order reference''' is the reference number of the customer, who receives the newly created key. 
The order reference and order number will be shown in the innovaphone license certificate.

[[Image:Created_activations.jpg|center|thumb|200px|created_activations.jpg/|created_activations.jpg/]]

You have to select an activation key in the activation key list to update or delete it.

Updating and deleting a key is only possible, if this key is not assigned.

====Update====
Add more licenses to this key or change its comment, order number and order reference. 
You can also remove licenses by entering e.g. -2, if you want to remove 2 licenses from the key.

[[Image:Own activations update.jpg|center|thumb|200px|own_activations_update.jpg/|own_activations_update.jpg/]]

====Delete====
Delete this key. Its licenses will go back into the balance of the currently selected project.

===Devices===
To view your devices you first have to click on the "Show" button. You can leave the filter field empty if you want to view all your devices.

[[Image:Devices_page.jpg|center|thumb|200px|devices_page.jpg/|devices_page.jpg/]]

Red marked device names are devices, which are currently in RMA.

MAC addresses of RMA devices do not longer start with 01-...

====List====
A List of your devices in the currently selected project. 
You can deselect the current project/device to list all your devices.

Select a certain device from the device list, to manage its properties, licenses etc.

Actions on multiple devices:
* Move: move several devices into another project at once (see [[#Move device|Move Device]])
* Remove: remove several devices at once (see [[#Remove|Remove]])

=====Add=====
Follow the "Add new devices" link on the devices page.

There you have a few options:
* You can add a single new device
* You can add devices according to a mac address range (e.g. from 00-90-33-08-20-00 to 00-90-33-08-22-00), maximum 50 at once
* You can add devices by uploading a text file with mac addresses like this (maximum 50 at once, each line one mac):

00-90-33-08-20-20
00-90-33-08-20-21
00-90-33-08-20-22
00-90-33-24-20-20

* You can add devices according to your received order number. Just enter you order number and you will get a list of all devices bount to this number.

Note: MAC addresses can be always given like this:
* 00-90-33-xx-xx-xx
* 00:90:33:xx:xx:xx
* 009033xxxxxx
* xxxxxx (00-90-33- will then be added automatically)

There might be errors, if you try to add a device. They are explained [[#Image explanation|here]].

As the device warranty will be handled by licenses now, you can also add telephone devices
to your projects.

=====Add warranty extensions=====

Here you can add warranty extension licenses for all devices in the currently selected project. 
You'll get a list of all devices with the corresponding license type(s) and you can specify the years for each device (or for all devices by entering the number in the list header). 
After confirming your selection, you'll get an overview of all needed licenses, which you have to confirm too.

=====Check licence, SSA and warranty status of a device=====
Here you can list licenses with ssa and the warranty end date of a device, which is not in one of your projects. 
For this option to work, you have to link your innovaphone customer ID (5 digits) to your my.innovaphone company. (As the warranty is also the one we grant to our distributors, we don't want to get an end customer confused.)

=====Download devices of an order as CSV=====
Enter an order number to retrieve all devices for this order in a CSV file.

=====Download devices of an order as PDF with barcodes=====
Enter an order number to retrieve all devices for this order in a PDF file with a barcode for each MAC address. 
Der Barcode ist vom Typ C128B.

====Properties====

Change the name and comment of a device.
You can only change the name, if it's no MAC or IPEI.
 
Here you have also the possibility, to directly request RMA for this device with prefilled values.

====Licenses====
Here you can add, download or move licenses.

=====Add licenses from balance=====
To create new licenses for a device, you have to add this device first on the devices page and then select a version of the license
and whether you want to summate the current licencing. If you select current licenses, then older licenses for example V6 or V7 licenses will also be counted as V8 licenses in the next overview. This is necessary if you want to license a V6 unit with V8 licenses, but still want to use it as V6.
After that click "Next".
On the next page you will see a list of all available license types, which depends on your current available license types, of the selected license version and the device type (IP6000, IP800 e.g.):
[[Image:licenses.jpg|center|thumb|200px|licenses.jpg/|licenses.jpg/]]
 
If your project has a SSA end date, which is not yet over, you'll have the possibility to set SSA for the new licenses to this SSA end date or you can optionally change this date to another one for the new licenses.
 
You see the available project balance, the balance over all projects (excluding external projects), the currently installed licenses and the maximum amount for this device type. You can now enter the value of the new license.
Base/Upgrade licenses can be selected via dropdown box.
'''Voicemail and Standby lics must always have the same amount as the selected PBX-PBX... license!
The maximum amount of PBX-Registration licenses equals the amount of the selected PBX-PBX... license!'''

The whished overall amount of pbx version 8 and above licenses can be specified here and the concrete amount of license sub types will be requested on the next page.

You can preview the SSC calculation of the wished licenses without having them in your balance.

[[Image:licenses2.jpg|center|thumb|200px|licenses2.jpg/|licenses2.jpg/]]

The best (cheapest) combination of each v8 pbx license type is already filled in, but you might change the amount of sub types if your does not fit and you do not want to purchase new activation keys for the sub types.

The column SSC/Unit is just shown if your project is currently under SSA and you have entered a SSA end date.

The SSC multiplicator is the value, which you have to multiplicate with each license unit to get
the corresponding SSC amount.
E.g. if you have 20 units of PBX-Port8*20 licenses with a SSC value of 54 and a multiplicator of
1.0000 (which equals to 365 days) you have to pay 20*54*1.0000 ~ 1080 SSCs.

 If you create licenses for an older version than the current version, you have to pay SSCs from the [[#Release dates|release date]] of the next version of the currently selected version twice. 
e.g.: you want to bind licenses for V6 with SSA, so you have to pay SSCs from the release date of V7
 You can also select for each license, if you want SSA for it or not. If not, no SSC is needed and no (new) SSA end date is set for this license. 

You can't change the SSA end date, if the project is under automatic SSA! You will receive an invoice for SSCs used for the new binding.

Now confirm your new selection. If you have not enough licenses in your current project, but there are still licenses in other projects, you will get a dropdown box with a list of all projects containing the needed licenses. You can now select all desired/needed projects and confirm your selection again.
The balance of all selected projects will then be decreased by the needed amount.
 
 
If your user account has the right to buy licenses on credit, just check the checkbox.
 
You may enter an order number, which you can use for your order, if you buy on credit.

=====Add licenses from free licenses=====

Here you can assign licenses, which you returned from other devices.
You will also have to select the desired version and will than get a list of fitting licenses according to the current device and selected version.

[[Image:licenses_free.jpg|center|thumb|200px|licenses_free.jpg/|licenses_free.jpg/]]

If a license is under SSA, the correct license type is shown in column 'License Type' besides the 'Original Type'.
On confirming the selection, a consistency check is done (e.g. only 4 Relay-PRI licenses on an IP6000).
Bind and SSA end date will be maintained for each license.

As external keys are also maintained, you can select e.g. an old Dect-Multicell-Ari license to have the same ARI on another IP1200.
 

If your project has a SSA end date, which is not yet over, you'll have the possibility to set SSA for the new licenses
to this SSA end date or you can optionally change this date to another one for the new licenses.
You will have to confirm this after your first license selection (this is the same calculation as [[#Software Service|here]]).

You can't change the SSA end date, if the project is under automatic SSA! You will receive an invoice for SSCs used for the binding.

=====Add V7 floating license (slave pbx)=====
Here you can add a V7 floating license for a slave pbx. A device with a floating license can't have V7 pbx licenses and a device with V7 pbx licenses can't have a floating license.

=====Delete V7 floating license=====
Here you can delete an already existing floating license, if you won't use it anymore.

=====Add warranty extension licenses=====
Extend your warranty by adding warranty extension licenses:

[[Image:add_warranty.jpg|center|thumb|200px|add_warranty.jpg/|add_warranty.jpg/]]

If you add the warranty extension immediately after the receipt of your device,
you can add the cheaper warranty extension licenses, otherwise you'll have to add
the more expensive ones.

You can extend the warranty for a maximum of four years.

=====Download licenses=====

[[Image:Device_download.jpg|center|thumb|200px|device_download.jpg/|device_download.jpg/]]

You will get a dropdown with all available versions. Versions are dependent of your device, your licenses and of the ssa of your licenses. 
'''From V9 on''', you just have one option, which will create a license file, which contains the licenses upgraded to the highest version of their type. 
You are able to download downgraded versions of your licenses. E.g. if you have only V8 licenses, you can download a V7 license file (same restrictions as below).

Downgrades or only possible down to version 6!

If you do not want to download licenses by version, you have to decide whether to download the licenses encrypted or not.
'''If you download the licenses unencrypted, you won't be able to return those licenses anymore.'''
So you won't be able to return licenses for devices with V5-V7 licenses, as licenses for these versions are not encrypted.
To return these licenses, you will have to upgrade to a new bootcode, which prevents firmware downgrades to versions below version 8. 
Encrypted licenses are stored in a xml file, which you can then upload on your V8 (or higher) device.

You can now also download licenses directly from by the web interface of a device.
You just have to enter your account data and start downloading the licenses from my.innovaphone.com
without having to download/upload a license file.

=====Download test licenses=====

[[Image:Device_download_test.jpg|center|thumb|200px|device_download_test.jpg/|device_download_test.jpg/]]

You can also download test licenses if you want to run tests. You will be asked, which version you want to use, whether the device is used as slave and if not used as slave, how many pbx licenses you want to use.

'''Important: Since V11, trial licenses are valid for 3 months and can be released once for a dedicated device. After expiration of those 3 months no further trial license creation for this device is possible.'''

V5 does '''not''' support test licenses!

=====Download App development license=====
If you're an App developer, you have the possibility, to generate a real license for you Apps which will contain your manufacturer prefix. 
The manufacturer prefix has to deposited at your my.innovaphone company by innovaphone before you can use this feature.

You can just have up to '''three''' different devices per company for which you can create such licenses!
These licenses aren't allowed for production usage!

You see your already used MAC addresses on this page too if you already created such licenses before.

If your manufacturer prefix is '''innovaphone''', you can enter license names like:
* App(innovaphone-app1)15
* Service(innovaphone-app2)15

=====Move licenses to another device=====
If you have the needed account rights or the device is already in RMA, you can move licenses to another device. After moving licenses, the former device will be marked as a RMA device.

You can just move licenses to devices without licenses!

=====Mix of rental and purchased licenses=====
From '''13r2 SR12''' onwards you can mix rental and purchased licenses. 
A device with rental licenses will be always inside a rental project (you recognize such a project by it's starting and ending '''$''' in the name). 
You can now add licenses from the balance to a device in such a rental project. 
 
If you invalidate lifetime licenses on such a device, just purchased licenses are returned. Rental licenses stay bound until you remove them inside your Devices App! (under rental menu)
Inside my.innovaphone you will always see both rental and purchased licenses. Inside the Devices App, you will just see the rental licenses. 
 
You must download and/or install the purchased licenses as usual. 
 
A 13r1 PBX or a PBX with an older SR will just recognize rented licenses!

If your PBX is already inside a non rental project, it will be automatically added to a rental project if you add rental licenses. You then may have the device in two different projects (one rental, one normal), which is no issue.

====Move device====
Here you can move the current device or the selected devices to another project. 
If you select a SSA project, you can change the SSA end date for the move process. 

If the other project is under SSA, you will first see a SSC calculation, which you have to confirm,
as the SSA date for each SSA license will be extended until the given SSA end date
(this is the same calculation as adding SSA to an already existing project, see [[#Software Service|here]]).

You can't change the SSA end date, if the other project is under automatic SSA! You will receive an invoice for SSCs used for the move.

====Invalidation====
====Returning of licenses====

By the invalidation, licenses are returned to the free balance of the project to which the device belongs in the Portal my.innovaphone. 
You can then bind the licenses from the free balance to another device.

=====Requirements=====
* V8 or higher
* access to the webinterface
* a device certificate
* my.innovaphone login credentials
* '''no IPVA device'''
* no 'In House' licenses

=====Informations=====

You can invalidate V8 (or higher) licenses by uploading the XML file, you got from your device or by returning your licenses over the web interface of your device ([[Reference12r1:Configuration/General/License]]), in order to return [[Reference15r1:Licenses#Gateway Licenses|PBX licenses]] back to the free balance.

V7 licenses can be just returned, if you agree, that you won't be able to downgrade below V8 anymore. You will need a new bootcode, to use this function. '''You need a V8 firmware or higher for invalidation.'''

If your device has access to my.innovaphone.com, you can also invalidate licenses directly from the web interface of the device.

[[Reference15r1:Licenses#Gateway Licenses|Gateway licenses]] and warranty extensions won't be returned to the balance and remain to be assigned to the device!

The licenses needn't be present on the local device to perform the invalidation!

SSA are bound to the license and not lost when performing invalidation.

=====Process=====

Steps to invalidate licenses, if your device has internet connectivity:
# on the web interface of the device go to General->License and follow the my.innovaphone link
# enter your my.innovaphone account, the device must be in one of your projects
# click Invalidate
# click Transfer (this might fail, if NTP or DNS is not configured properly or device certificate is not installed)
# reset if asked for

Steps to invalidate licenses, if your device has no internet connectivity:
# on the web interface of the device go to General->License and follow the my.innovaphone link
# click Invalidate
# click Backup and upload this file on my.innovaphone [[#Upload the invalidation document to return licenses|here]] (Licenses->Devices (select the corresponding device)->Invalidation)
# you'll get a confirmation file after uploading the saved file
# upload this on the device (under Step1)
# reset if asked for

"Your IP800 does not have a device certificate on it." - In this case you need to download a hardware certification,
please contact the innovaphone [mailto:license@innovaphone.com license department].

=====Download confirmation file=====
If you created a new certificate or you invalidated your licenses, you can later download the confirmation file, which you have to upload on the box.

=====Request certificate=====
If you have the needed rights, you can request a new device certificate for your device.

=====Upload the invalidation document to return licenses=====
Licenses->Devices (select the corresponding device)->Invalidation:

Upload the invalidation document, which you got from the website of the device to return the licenses of this device.

After uploading you'll get a confirmation file, which you have to upload on your device.

====Remove====
You can always remove devices from a project. If they have licenses, these won't be deleted, so you might add the device to another project again.

===History===
[[Image:history.jpg|center|thumb|200px|history.jpg/|history.jpg/]]
You can view your history for several contexts:
* Company: history of all actions in your company
* User: history of all actions of the selected user
* Device: history of all actions for the selected device

Each context applies to the currently selected project.
If you deselect the current project, you will see the history over all projects.

You can select to view the history of the last day, week, month, year or from always. Collecting data might take a while...

===Company===
Manage users SSA expiry email flag, import other companies or add your companies innovaphone ID.

====Users====

You can just edit the SSA expiry email flag here. The other user settings moved to the [[#Authorized Persons| Authorized persons tab]].

====Join (admin only)====
As admin you can also join another company into your company by entering an admin account of this company. This might be usefull if one user of your company has accidentally created an own company. 
Everything like projects, users, devices, balance, activations etc. will be imported! 
You also have to enter the company id of the company, which is to be imported. You can find this company under Licenses->Company and the company tab.

This is not available for non company admin users.

The joined company will be deleted afterwards!

====Company====

You can check the '''Device SSA''' checkbox, if you want to receive SSA expiry reminder mails for each device independent of the projects SSA end date.
These mails will be send weekly seven weeks before the SSA for a license a the device expires.
 
 
You can also enter additional email addresses, which should receive SSA emails.
 
You can define a global '''end user expiry mail text''' here, which will be sent to end users, if end users are configured in a [[#SSA Expiry Mail| project]]. This text can be overridden by a text in a project under [[#SSA Expiry Mail| SSA Expiry Mail]].

==RMA==
Here you can see all your RMA devices, which arrived innovaphone already. The licenses of this macadresses are moveable.
[[Image:rma.jpg|center|thumb|200px|rma.jpg/|rma.jpg/]]
 
If you want to request RMA for a certain device, go to the device properties and follow the "Request RMA" link.

==Support==
===Mantis===
Here you'll get a list of all open cases and [[Understanding the innovaphone trouble ticket status page#Information available| additional info regarding their state]] in our ticket system. This list is composed of all tickets assigned to email addresses of your my.innovaphone users in your company. 
Often used functions:
* You can click on the ticket number ("ID" column) to open an email prepared with the right emailadress and subject to address this case.
* You can click on the ''History'' link to get an overview of the already made communication with our support/presales-team.
* Another important new function is the option to upload larger files to your support/presales tickets using the ''Fileupload'' column.

===Announcements===
You can convert audio files into G.7xx files which you can use as announcements. 
 
;Supported input formats:
* mp3
* wav
* ogg
* flac
* ...

;Generated output formats:
* G.711u
* G.711a
* G.729
* G.723
* G.722

==Image explanation==

===Errors===

====Already In Company====
[[Image:Icon_in_company_inno_01.png|icon_in_company_inno_01.png/|icon_in_company_inno_01.png/]]
* This device already exists in your company and can't be added/imported.
If you want to import this device anyway, you first have to delete your current device from its project.

====Already Imported====
[[Image:Icon_imported_inno_01.png|icon_imported_inno_01.png/|icon_imported_inno_01.png/]]
* This device has been already imported.
You can't import it again.

====Not Found====
[[Image:Icon_not_found_inno_01.png|icon_not_found_inno_01.png/|icon_not_found_inno_01.png/]]
* This device was not found in the my innovaphone database.
This should never happen, but if, contact the administrator.

====IPVA MAC exists====
[[Image:Icon_ip_va_exists_inno_01.png|icon_ip_va_exists_inno_01.png/|icon_ip_va_exists_inno_01.png/]]
* An IPVA MAC address must be unique and can be assigned to just one company. You tried to add an already existing IPVA MAC.
Please assign a new one to your IPVA. For further details, see [[Reference13r2:Concept_Innovaphone_Virtual_Appliance#License_Configuration]].

my.innovaphone supports the following MAC address ranges:
* 00-50-56-...
* 00-15-5d-...
* 00-03-ff-...
* 00-0d-3a-...
* 00-12-5a-...
* 00-17-fa-...
* 00-50-f2-...
* 00-1d-d8-...
* 00-05-69-...
* 00-1c-14-...
* 00-0c-29-...
* 00-1d-db-...
* 5a-ad-1d-...
* 48-e9-ca-...
* 02-01-04-...
* bc-24-...
* e2-... ''this is an autogenerated MAC address of innovaphone cloud containers''

===Warnings===

====Several Companies====
[[Image:Icon_several_companies_inno_01.png|icon_several_companies_inno_01.png/|icon_several_companies_inno_01.png/]]
* This device is already in another company.
This means, that either you do not have the physical device or it once belonged another company.
You can still import/add this device and you will have access to all of its current licenses.

====Several Users====
[[Image:Icon several users inno 01.png|icon_several_users_inno_01.png/|icon_several_users_inno_01.png/]]
* This device has licenses from several users of the old license manager.
This means, that you are not neccessarily the user, who physically owns this device. If you do not own it, do not import it.

===Misc===
====No downgrade====
[[Image:no_downgrade.png|no_downgrade.png/|no_downgrade.png/]]
* Licenses, which have been downloaded for V5/V6/V7, were returned from this device, so no downgrade to these versions is allowed any more.



==Release dates==
V5: January 1st 2003 
V6: November 2nd 2006 
V7: November 14th 2008 
V8: December 7th 2009 
V9: April 26th 2011 
V10: July 8th 2013 
V11: February 9th 2015 
V12: July 11th 2016 
V13: May 13th 2019 
V14: December 20th 2023

V15: March 25th 2025 



==External interface==

There is an external interface, which you can use to control some functionality without a login to the my.innovaphone web site. 
You can use the interface with an '''HTTP GET''' request to the following URL: 
 
'''<code>https://my.innovaphone.com/interface.php</code>'''

Configure a trust value and a URL (can be a dummy URL if not used otherwise) unter Licenses -> Project -> Properties and tick "Configure Update-URL"

===General parameters for all commands===
:;cmd: the wished command
:;email: the email address of a user who is registered in my.innovaphone
:;project_id: the project ID of the project where the user has access to (you can find the project ID under [[#Properties| Licenses->Projects->Properties]])
:;hash: an SHA256 hash value which is computed over all GET parameters but the hash parameter itself plus the '''trust''' value of the project (see [[#Properties|Reference:My_Innovaphone#Properties]])
:;hash: the values of the GET parameters have to be URL encoded before calculation of the hash

;Example: URL <code>https://my.innovaphone.com/interface.php?cmd=addDevice&email=user@example.com&project_id=123456&serial=00-90-33-01-02-03&hash=b62f7948d6383cc365592ed289b6173cd35229cadc347847b953f78c8880d5b9</code>
:;project trust value: 1234567890abcdef
:;the data of the SHA256 hash: ?cmd=addDevice&email=user%40example.com&project_id=123456&serial=00-90-33-01-02-03&trust=1234567890abcdef
:;example PHP function call to generate the hash: hash("sha256", "?cmd=addDevice&email=user%40example.com&project_id=123456&serial=00-90-33-01-02-03&trust=1234567890abcdef");
:;with the current values, the function should return: b62f7948d6383cc365592ed289b6173cd35229cadc347847b953f78c8880d5b9

===Add a device to a project===
;HTTP GET parameters:
:;general parameters
:;cmd: '''addDevice'''
:;serial: the serial number of the device, e.g. 00-90-33-01-02-03
:;[device_desc]: optional, a description for the new device

;Return value: a JSON object is returned
:;success: boolean, either '''true''' or '''false'''
:;error: string, a string with an error. Just existent if success is false
:;example success: <syntaxhighlight lang="javascript">{ "success":true }</syntaxhighlight>
:;example error: <syntaxhighlight lang="javascript">{ "success":false, "error":"the project with ID 123456 doesn't exist" }</syntaxhighlight>

===Remove a device from a project===
;HTTP GET parameters:
:;general parameters
:;cmd: '''delDevice'''
:;serial: the serial number of the device, e.g. 00-90-33-01-02-03

;Return value: a JSON object is returned
:;success: boolean, either '''true''' or '''false'''
:;error: string, a string with an error. Just existent if success is false
:;example success: <syntaxhighlight lang="javascript">{ "success":true }</syntaxhighlight>
:;example error: <syntaxhighlight lang="javascript">{ "success":false, "error":"the project with ID 123456 doesn't exist" }</syntaxhighlight>

===Get the warranty of a device===
;HTTP GET parameters:
:;general parameters
:;cmd: '''getWarranty'''
:;serial: the serial number of the device, e.g. 00-90-33-01-02-03

;Return value: a JSON object is returned
:;success: boolean, either '''true''' or '''false'''
:;error: string, a string with an error. Just existent if success is false
:;warranty: a unix timestamp in seconds since 1970 (timezone Europe/Berlin), e.g. '''1448492400'''
:;warrantyStr: a string like '''"2015-11-26 00:00:00"'''

===Create a new project===
;HTTP GET parameters:
:;general parameters: you must use the project_id and trust value of an already existing project!
:;cmd: '''createProject'''
:;project_name: the name of the new project
:;[project_desc]: optional, a description for the new project
:;[update_url]: optional, an update URL for the project (do not forget to URL encode the value inside your HTTP GET request!)
:;[ssa_due_date]: optional, a unix timestamp in seconds since 1970 (timezone Europe/Berlin), e.g. '''1448492400'''

;Return value: a JSON object is returned
:;success: boolean, either '''true''' or '''false'''
:;error: string, a string with an error. Just existent if success is false
:;projectId: the project id of the created project

The newly created project is created with the same trust value which was used for the creation request. This allows you to directly use the API with the new project.

==Known Issues==
===Smaller issues===
* Devices where imported into a project with SSA. If this happened to you, please move the corresponding devices into a project '''without''' SSA and back into the project '''with''' SSA to extend/add SSA for the licenses until the SSA end date.
* IE7 moves a list under the menu, when a list becomes to wide
===Licenses don't work on a device, where an invalidation has been done===
A possible reason here is, that the invalidation process hasn't been completed.
To resolve this issue, follow these steps:

* Download the Confirmation File (Certificate) from http://my.innovaphone.com under [[#Invalidation|Invalidation]] after selecting the project and the device
* Open [[Reference9:General/License/my.innovaphone|General->License->my.innovaphone.com]] on your device
* Click on "Invalidate" (no my.innovaphone credentials needed)
* Upload the previously downloaded confirmation file newcert-00-90-33-xx-xx-xx.xml as "Confirmation file"
* Reset the box
* Reupload the licenses

===Internet Explorer doesn't work===
Yes, that's correct. Please use an up to date version of Chrome, Firefox or Edge!

Reference16r1:Concept App Service IP

2026-02-27T12:58:33Z

Dde: /* Troubleshooting */

[[Category:Concept|Apps]]
[[Category:Concept|IP]]

The App IP is an app which offers the PBX functionality and further functionalities as App service on our innovaphone App Platform.

== Applies To ==

* innovaphone firmware and apps V16

==Requirements==
* innovaphone Application Platform (image version 140011 or higher)

==Concept==

The App IP offers modules known from innovaphone gateways, like the PBX, TURN server functionality etc.

==How it works==

=== Single instance mode ===
Unlike other App Services, the App IP is a single instance App Service, so you can create '''just''' a single instance and not multiple instances.

== Licensing ==
Standard licensing mechanisms apply to the App IP as they apply to innovaphone gateways.

In addition, every port license requires a dedicated IPAP license (similar to the IPVA license for virtual machines).

== Apps ==

There is no App provided by this App Service.

== PBX Manager Plugins ==

There is no PBX Manager Plugin provided by this App Service.

== Configuration ==

The configuration is done as an innovaphone gateway is configured too.

=== Advanced UI ===
The advanced UI is reachable under the webserver path of the App IP instance and /admin.xml?xsl=admin.xsl, e.g.:
https://domain.com/ip/admin.xml?xsl=admin.xsl

==Troubleshooting==

The App IP offers standard tracing mechanism for App Services and in addition mechanisms known from innovaphone gateways. 
You can enable module related trace flags with config change commands or by setting trace flags under Maintenance -> Tracing in the Advanced UI of the App IP.

Trace files are not found under Maintenance -> Tracing but on the App IP service on your App Platform Manager.

==Known issues==

==Related Articles==
* [[Reference16r1:Concept_innovaphone_App_Platform_Docker_Container]]

Reference16r1:Concept App Service IP

2026-02-27T12:56:54Z

Dde: Created page with "Apps IP The App IP is an app which offers the PBX functionality and further functionalities as App service on our innovaphone App Platform. == Applies To == * innovaphone firmware and apps V16 ==Requirements== * innovaphone Application Platform (image version 140011 or higher) ==Concept== The App IP offers modules known from innovaphone gateways, like the PBX, TURN server functionality etc. ==How it works== === Single in..."

[[Category:Concept|Apps]]
[[Category:Concept|IP]]

The App IP is an app which offers the PBX functionality and further functionalities as App service on our innovaphone App Platform.

== Applies To ==

* innovaphone firmware and apps V16

==Requirements==
* innovaphone Application Platform (image version 140011 or higher)

==Concept==

The App IP offers modules known from innovaphone gateways, like the PBX, TURN server functionality etc.

==How it works==

=== Single instance mode ===
Unlike other App Services, the App IP is a single instance App Service, so you can create '''just''' a single instance and not multiple instances.

== Licensing ==
Standard licensing mechanisms apply to the App IP as they apply to innovaphone gateways.

In addition, every port license requires a dedicated IPAP license (similar to the IPVA license for virtual machines).

== Apps ==

There is no App provided by this App Service.

== PBX Manager Plugins ==

There is no PBX Manager Plugin provided by this App Service.

== Configuration ==

The configuration is done as an innovaphone gateway is configured too.

=== Advanced UI ===
The advanced UI is reachable under the webserver path of the App IP instance and /admin.xml?xsl=admin.xsl, e.g.:
https://domain.com/ip/admin.xml?xsl=admin.xsl

==Troubleshooting==

The App IP offers standard tracing mechanism for App Services and in addition mechanisms known from innovaphone gateways. 
You can enable module related trace flags with config change commands or by setting trace flags under Maintenance -> Tracing in the Advanced UI of the App IP.

==Known issues==

==Related Articles==
* [[Reference16r1:Concept_innovaphone_App_Platform_Docker_Container]]

Howto:Pcap

2025-11-19T06:38:50Z

Dde: /* Versions */

With remote PCAP, network traffic can be captured directly from another network device, instead of capturing the network traffic from the own device.

==Remote PCAP==
===Requirements===

* You should have installed the latest wireshark Stable release 4.4.x - [http://www.wireshark.org/download.html Wireshark Download]
: You may also use newer builds, but make sure they are supported by our plugin DLL. See [[#Versions | Versions ]] below for a list of supported versions
* To view the standard debug output of ISDN LAPD/Q.931 packets, you have to install the ''innovaphone plugin'' (<code>innovaphone_win32.dll</code> or <code>innovaphone_win64.dll</code>, depending on your installed wireshark version, 32 bit or 64 bit). To convert text log output (from the ''Maintenance/Tracing'' page) you can use ''log2pcap.exe''.
*To download both items, go to the [http://store.innovaphone.com innovaphone AppStore] under the tab '''Software''' , select the latest version of '''log2pcap''' and '''Wireshark DLLs''' .
: Again, if you use newer builds, make sure you download the DLLs from the appropriate ''apps'' package (see [[#Versions | Versions ]] below)
: To '''install''' a DLL version '''1059''' or previous, just copy it to your wireshark plugin directory and pay attention on your currently used version (e.g.: c:\programme\wireshark\plugins\1.12.0\). Note that you need to re-install the DLL each time you update wireshark
: To '''install''' a DLL version '''1060''' or later, just copy it to your wireshark plugin '''epan''' directory and pay attention on your currently used version (e.g.: c:\programme\wireshark\plugins\4.4\epan\). Note that you need to re-install the DLL each time you update wireshark
* Open the [http://wiki.innovaphone.com/index.php?title=Image:Pcap_example_isdn.zip example pcap file with lapd and q.931 packets] to check your current installation. It should look like this, if you have the innovaphone_winXX.dll correctly installed:

[[Image:Pcap_sample_isdn.jpg|center|thumb|200px|PCAP ISDN example]]

==== Using Wireshark ''Legacy'' ====
Starting with version 2, wireshark has a new user interface. Unfortunately, we found this to be sluggish and buggy. For that reason, we strongly recommend to use wireshark's ''legacy'' version. It is available as an option (''Wireshark 1, The classic user interface'') in the installer's item selection. You also may want to associate the trace file extensions (.pcap, .pcapng etc.) with ''Wireshark Legacy'' instead of the standard version (also available in the setup dialogue).

===Setting up the rpcap server===

* The rpcap server can be any innovaphone device.
* The remote pcap server is disabled per default. To enable it, just go to Diagnostics->Tracing and check the "Enable" flag in the "Remote PCAP" group. If you are experiencing problems, also enable the trace flag with "config add PCAP /trace".
* To capture all ip traffic (udp and tcp), enable the "IP (all tcp/udp traffic)" flag in the group "IP". Otherwise just enable all the trace flags on the modules you want to capture.

===Capturing with wireshark===

===1.x.x - 1.7.x===
Open your wireshark and the capture options dialogue. Choose "remote" from the dropdown list and
Type "<IP-ADDRESS>/TRACE" into the host field.

It should look like this: (Screenshot from older Wireshark, v.1.2.2)
[[Image:Wireshark_1.2.2_trace_settings.PNG|center|thumb|200px|Wireshark capture options]]

Then just click on "Start" to start capturing.
 

=== >= 1.8.x ===

Open your wireshark and „Capture Options“->“Manage Interfaces“->“Remote Interfaces“. Add the IP address of your device. 
The remote interface will be listed in your interface now and you can select it for capturing data.

[[Image:Wireshark_1.8.6_settings.png|center|thumb|200px|Wireshark capture options]]
 

=== >= 2.0.0 ===

[[Image:Wireshark_2.0.0_settings.jpg|center|thumb|200px|Wireshark capture options]]

=== >= 3.0.0 ===

With the latest innovaphone Firmware (e.g. 13r1 SR11), Wireshark is supported again if you use the latest wireshark DLL. 
 
If you're running older firmware versions: 

The innovaphone.dll is not supported currently with this Wireshark-version. Please do not upgrade to Wireshark 3.0 or up.

RCAP does not currently work with innovaphone devices in newer Wireshark versions. If you only want to pull general remote PCAPs with it, you can also try the Wireshark Pipe feature. For this you have to create a new pipe interface in Wireshark in the following format.
<syntaxhighlight lang="bash">
rpcap://[ip-address]/trace
</syntaxhighlight>

During our tests we experienced some problems with it. Alternatively, you can add the pipe interface via the command line. First change to the Wireshark directory and replace [ip-address] with the innovaphone IP address.
<syntaxhighlight lang="bash">
C:\Program Files\Wireshark>wireshark -ni rpcap://[ip-address]/trace
</syntaxhighlight>

=== >= 4.0.7 ===
Wireshark doesn't support 32bit Windows builds anymore, so there is just a 64bit version of the DLL now.

===Supported protocols===

* ISDN: LAPD L2/L3 with dissector innovaphone.dll (enable Diagnostics->Tracing TELX/PRIX/PPP)
* AC DSP: dsp with dissector Ac49xPacketRecording.dll (enable Diagnostics->Tracing->VOIP DSP)
* PPPoE: flag "/pcap" on module(s) PPPOE0/PPPOE1 enables pcap tracing

* All TCP/UDP protocols which are supported by native wireshark dissectors or other dissectors which can be found searching the internet.
e.g.:
SIP
H.323
H.245

Enable the corresponding flags under Diagnostics->Tracing, if you only want to see specific UDP/TCP protocols. To see all, enable the "All TCP/UDP Traffic" flag under Diagnostics->Tracing.

==PCAP Log==

Another possibility to get a pcap log file is to open http://IP/log.pcap
This file has a limited size just as the normal log file.

==log2pcap==

You need the tool log2pcap from the tools package, if you have a log.txt file, which contains pcap packets and you want to view them in wireshark. You can find the tool in the apps tool package (see above).

Usage:
# log2pcap.exe input1 input2 ... inputX
# drag&drop one or more files on the log2pcap.exe
# use an asterisk like "log2pcap c:\*.txt" to convert all txt files into pcap files. Things like c:\test*.txt are not supported.

* The resulting file name is always inputx.pcap (e.g. log.txt is converted into log.txt.pcap).

Note: if you have a trace of a little endian box (e.g. IP3000, IP21) with V6 SR1 or SR2, you have to use the "-srlefix" switch (available since 08-1007):

log2pcap.exe input1 -srlefix

==General Informations==

===Reading PCAP Traces===

====Non-IP Pcap packets====
It will nevertheless show source and destination IP addresses. 127.0.0.1 stand in for the traced device. So if for example a Q.931 SETUP messages is sent from 127.0.0.0 to 127.0.0.1, then it is an incoming setup.

====MAC: 00:90:33:00:00:00====
Sometimes people wonder why a pcap ''00:90:33:00:00:00'' appears as source or destination mac address.
The direction of the packets can be analyzed based on the Mac address.
: We use the devices MAC adress as source only if a packet '''is sent'''
: We use the devices MAC adress as destination only if a packet '''is received'''
The other field will be filled with ''00:90:33:00:00:00''

===Disabling PCAP traces===

You can disable the whole pcap tracing. Just configure a /disable-pcap to the CMD0 module. This can be useful if you do not want to see pcap traces in your log file.

===Used ports===

* The debug traces are encapsulated in UDP packets with port 4.
* The isdn traces are encapsulated in UDP packets with port 4.
* The ac dsp traces are encapsulated in UDP packets with port 50001.
* Wireshark uses port 2002 to connect to the running rpcap-server
* rpcap packets are transfered over a dynamically assigned port between server and client

===Additional Remote PCAP trace===

You can trace the remote pcap protocol with adding the trace flag by "config add PCAP /trace" if you are experiencing connection issues.

===Timestamps===

Since V7 Hotfix 26 and V8 Hotfix 13, the ntp timestamp is used instead of the uptime in rpcap packages. In converted log files with log2pcap, uptime is still used.

===Decode TURN Traffic as RTP===
RTP Traffic encapsulated in TURN and encoded as STUN per default. You can change this behaviour as global setting in your Wireshark. 
To activate RTP heuristic for TURN traffic go to "''Analyze::Enabled Protocols''" and enable the "''rtp_stun''" dissector.

==Versions==
Older versions can be downloaded from the respective [http://download.innovaphone.com/ice/download/p/6.00/apps/ ''tools'' package]:
* Wireshark 1.6.8: DLL Version 1043 - V6 6000043 Application Packet
* Wireshark 1.11.1: DLL Version 1049
* Wireshark 1.12.2: DLL Version 1055 - V6 6000054 Application Packet
* Wireshark 2.0.x: DLL Version 1057 - V6 6000055 Application Packet
* Wireshark 2.2.x: DLL Version 1058 - V6 6000056 Application Packet
* Wireshark 2.4.x: DLL Version 1059 - V6 6000059 Application Packet
* Wireshark 2.6.1: DLL Version 1060 - V6 6000061 Application Packet

Newer versions can be downloaded from [https://store.innovaphone.com the store] (look for ''Wireshark DLLs'' in the ''Software'' tab):
* Wireshark 3.2.x: DLL Version 1061
* Wireshark 3.4.x: DLL Version 1066
* Wireshark 4.0.x: DLL Version 1068
* Wireshark 4.2.x: DLL Version 1069
* Wireshark 4.4.x: DLL Version 1070
* Wireshark 4.6.x: DLL Version 1071

== Offline generation of PCAP Files ==
In version v12r1 and up, you can capture and store PCAP files without running Wireshark. This is done by setting the [[Reference12r1:Maintenance/Diagnostics/Tracing | ''Write PCAP to URL'' property ]] in ''Maintenance/Diagnostics/Tracing'' to an URL which points to a writeable WebDAV folder.

This is useful if you need to trace a device for a long time or if you cannot run Wireshark to capture the trace. However, it is not useful if the traced device restarts, as the last trace file will be incomplete then (due to buffered IO when writing the file).

When you remove the URL, the current trace file will be flushed and no further one will be created.

=== Using V13 File App ===
*create a folder in the File App
*share this folder with username and password
*copy the URL from this folder
*go to services/http/client on the innovaphone device for which you need a pcap and store the URL and access data here
*store the same URL as "Write PCAP to URL" at maintenance/diagnostic/tracing

Attention:
As soon as the URL was successfully deposited and "OK" was pressed, the trace is written into the folder.
To end the trace, the URL can simply be removed and confirmed again with "OK".

==Known Problems==

* Converting a log from a little endian box (like IP3000 and IP21) with firmware V6 SR1 or SR2 with the tool log2pcap will only work with log2pcap 08-1007 or higher and the switch "-srlefix", see [[:#log2pcap|log2pcap]].
* Ac49xPacketRecording.dll works only with 0.99.7. Higher versions of wireshark won't start, if this dll was copied to the dll folder!
* Also some other dlls, contained in the tools package, won't work with each wireshark version. Just innovaphone.dll is always working.
* Even though ''All TCP/UDP Traffic'' is turned on, packets sent to the box acting as rpcap provider to a port that is not handled by the box (that is, where no listening socket is active) will currently not be shown
* If you use a 64-bit Windows Pc then you will need another innovaphone.dll, which is also contained in the latest tool package.
* The custom IP header from captured innovaphone packets contains dummy values for TOS (0), id (0), fragment offset (0) and TTL (128)
* After version 1.8.6 of wireshark the h225 packets are listed as malformed. So higher versions of wireshark could give troubles debugging the h.323 calls.
* '''Couldn't set the capture buffer size!''': if you're experiencing this error message, please start wireshark with the option "-B 1" to set the buffer size to 1 MB

* Wrong time stamp when using PCAP-to-URL:
** open the first frame of the trace and expand the 'innovaphone: DEBUG'-section
** last line shows the correct time: 'Debug: YYYY-MM-DD HH:MM:SS' in this case
** Click on 'Edit -> Time Shift...' in the menu or use the shortcut Ctrl+Shift+T
** Tick 'Set the time for packet 1 to ...' and fill in the time found in the first frame
** Click 'Apply'

===Missing msvcr120.dll or "module not found"/"Das angegebene Modul wurde nicht gefunden"===
You have to install the Visual C++ Redistributable Packages für Visual Studio 2013: http://www.microsoft.com/de-de/download/details.aspx?id=40784

===Inconsistent timestamps with Write PCAP to URL===
There are sporadically inconsistent timestamps where a newer packet might have an older timestamp than the previous packet (a fraction of a second). 
This issue just happens with Write PCAP to URL and the default configuration. This issue has been [[ReleaseNotes14r1:Firmware#157768_-_Firmware:_fixed_wrong_timestamps_in_%22Write_PCAP_to_URL%22_feature | fixed]] in the 14r1 release, so the workaround below is no longer needed. 
 
If you use Wireshark for jitter analysis and consistent timestamps are important, you may do a configuration change:
* disable the epoch-ts option on the PCAP module:
** !config add PCAP /epoch-ts false
** !config write
** !reset
* now the PCAP trace just contains the uptime beginning from 1970-01-01 but without any wrong timestamps
* Wireshark offers an option to set the time on the first packet, so the time can be manually set to the file creation time (right click first packet -> move time -> second option and enter e.g. "2023-01-03 13:30:00")

==Related Articles==
* [[Reference12r1:Maintenance/Diagnostics/Tracing]]

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

Reference14r2:General/Devices-Registration

2025-10-23T11:15:44Z

Dde: Created page with "The Devices App URL can be configured here. This URL is used to establish a websocket connection to the Devices App and register there. Example: <code>wss://ap.innovaphone.com/innovaphone.com/devices/sysclients</code> The Format is: wss://''[dns-ap-platform]''/''[system domain]''/devices/sysclients If the connection between the device and the Devices App is up, there is "Up, X sessions" shown. If there is someone browsing on the UI of the device through the Dev..."

The Devices App URL can be configured here. This URL is used to establish a websocket connection to the Devices App and register there. 

Example: <code>wss://ap.innovaphone.com/innovaphone.com/devices/sysclients</code>
The Format is: wss://''[dns-ap-platform]''/''[system domain]''/devices/sysclients

If the connection between the device and the Devices App is up, there is "Up, X sessions" shown. 
If there is someone browsing on the UI of the device through the Devices App, the session counter is increased.

==== Implicit changes of the ''Devices App URL'' ====
The old mechanism to reconfigure devices according to the PBX App object of Devices has been removed in the latest service releases. 
Instead an expert configuration can be used to rollout a new ''Devices App URL'' to connected devices.

Reference15r1:Concept App Service Devices

2025-10-15T05:03:38Z

Dde: /* Certificates configuration */

[[Category:Concept|Apps]]
The App Service Devices is an App Service which can be installed on an innovaphone App Platform. It is used to administrate the innovaphone devices which belong to the whole installation.
== Applies To ==

* innovaphone PBX from version 13r1

== Apps ==

=== Devices App (innovaphone-devices) ===
This is the standard UI App for Devices.

Parameters:

;Websocket: to publish the com.innovaphone.devicesui-API, which can be used to link directly to devices (which is done e.g. inside the Events app)

=== Devices API (innovaphone-devices-api) ===
This is a hidden App, which provides the Devices API (com.innovaphone.devices). This API can be used to find and communicate with devices which are registered to the Devices App.

Additionally it acts as a provider of the Search API (com.innovaphone.search). So you can find devices and domains in other apps like the Search App.

Parameters:

;Hidden: DevicesApi must be a hidden App
;Websocket: to get the URL of the Devices App itself which is used for provisioning

== PBX Manager Plugins ==

=== Devices ===

With the Devices plugin App objects can be created, edited and deleted for Devices and the Devices API on the PBX.

== Concepts ==
All innovaphone hard phones and gateways starting from version 13r1 can establish a registration inside the Devices App and therefor administrative tasks can be performed through the App.

=== Domains ===

In a hosted environment, it might be needed to add multiple domains to the Devices App. 
After the initial installation of Devices through Install, you have administrative rights and can add more domains.

==== Administrative rights ====
You have administrative rights if the configured PBX App object for Devices uses the password of the instance which is configured in the Manager App and the PBX uses the same domain as this instance.

==== Domain local rights ====
You have just rights to a certain domain if the configured PBX App object for Devices uses the domain password which can be configured in Devices for each domain and the PBX uses the same domain name as configured in Devices.

==== Assign rights to other domains ====
Domains can gain access to other domains by configuring these access rights in the Devices App.

==== Deploy passwords and access rights ====
During install, a domain is created inside the Devices App. There is a checkmark Deploy the domain password on all devices which is set by default and which is the same as the administrative password.
If you change the domain password, all passwords on all administrative devices and app platforms which are connected to this domain will be also changed. 
Since 13r2sr25/13r3sr7/14rx: devices which are auto provisioned or provisioned through the Profile/Users Admin App will get a random password instead of the domain password.
If you add a phone device manually to a domain inside the Devices App, this phone device will also get a random password. Other device types added manually or devices added with a provisioning code which has been created within the Devices App directly, will get the domain password instead. 
 
This will also set the manager password and the SSH passwords of App Platforms. 
 
The clear text random passwords can be requested and viewed in the settings of a device in the Devices App.

Attention: If you untick the '''Deploy administrative devices passwords''' checkmark, the password won't be deployed anymore, but also not reconfigured to the default password!

Attention: After each reconnect of a client, the password will be deployed again.
This means, if the checkmark is set and you set another password somewhere else (e.g. under General::Admin),
this password will be just valid until the next reboot or reconnect to the Devices App!

;Create new random passwords
You can rollout new random passwords by unticking the '''Deploy administrative devices passwords''' checkmark and ticking it again. 

;Devices with multiple domains (Cloud)
In a hosted environment, you can use the Devices App with multiple domains. The corresponding instance of Devices has a configured domain and an instance password set inside the manager. 

The hosting PBX has a domain inside Devices with a specific password. 
If this domain name matches the instance domain of the Devices instance and the password matches either the instance password or the domain password, you will be logged in as admin and have access to all domains. 

Each newly created domain has its own password inside Devices. If you create an App Object inside a PBX with this domain and the password of this domain (inside Devices), you will just have access to this single domain. 

Devices also has the possibility to grant access to other domains for a specific domain.

=== Categories ===

There are two types of categories:
* provisioning category: used for device configurations and provisioning
* standard category: used for update/backup jobs and device management

Each device can have just a '''single''' provisioning category, as it receives it's configuration by all configured device configurations for this provisioning category.

In addition, a provisioning category, which is used inside an analogue phone/phone device configuration '''cannot''' be used to provision a gateway.

=== Device connections ===
The Devices registration is done through a websocket connection to the webserver of the App Platform and the Devices instance (standard HTTP/s port). 
The URL used can be configured manually under [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:General/Devices_Registration Devices Registration] or through a new provisioning mechanism. 
 
A binary protocol is used to transfer information between the device and the devices App. The MAC address is the unique key to identify a device. 
 
If a device is added to a domain in Devices, the device gets a unique random password. Without such a password, a device shows up as '''unassigned''' in the Devices app.
This is also the case after a long reset or when the device lost its configuration. 
 
In such a case, the device has to be manually added again to a domain or it has to be provisioned again.

If a device is not assigned to a domain or provisioning category, it won't receive any configurations.

==== Devices Registrations ====
See [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:General/Devices_Registration Devices Registration]

==== Second Devices Registration URL ====

The firmware has a second SYSCLIENT2 module, which can be configured to point to a different Devices instance and the AP Manager also has a second Devices Registration URL. 
 
If you use this configuration option, you should take care and consider:

* if the Devices domain from the second configuration provides a password for all devices, the password is ignored, as it would lead to inconsistend passwords otherwise (from 13r1 SR12 on)
* the Devices domain from the second configuration should not provide Devices Configurations or Update Jobs as these might collide with configurations from the first Devices instance!

Generally, only one of the two ''Devices'' App instances connected to the device must apply changes to the device.

We strongly discourage the usage of this second configuration option due to unexpected behaviour if incorrectly used!
Never use the second URL if you use software or hardware rental!

==== Device information ====

The following data is transferred:
* MAC address
* device type (e.g. IPVA, AppPlatform, IP112)
* IP addresses (IPv4, IPv6)
* version (not searchable)

You can also search for this data inside the devices tab in the App.


=== Provisioning ===
Devices can be added by provisioning (both phones and gateways).
The standard online provisioning looks like this:
* a user or administrator creates a provisioning code in the Devices or Users App (this stores the Devices URL on the provisioning server side)
* a device with 13r1 or newer is connected to the network after a long reset
* the provisioning code has to be entered within one hour (after one hour, the Update URL isn't polled anymore)
* the device sends this code to config.innovaphone.com and retrieves the Devices URL
* the device connects to the Devices URL and is added to the domain where the code has been created

There is also an [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Offline_Provisioning offline provisioning mode]. 
There is also an [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Provisioning#Automatic_provisioning automatic provisioning mode].

Note: provisioning is cancelled if the device already belongs to another domain in the same Devices instance! This prevents the unauthorized move of a device between different domains.

==== Devices Registration URL ====

The Devices Registration URL which is set through the provisioning process, always starts with '''wss'''. This is not dependent anymore on the App URL which is configured inside the PBX Devices App object.

=== Updates ===
The Devices App can be used to rollout updates. 

==== JSON files ====
The update files have to be acccessible on a webserver without authentication and four json files are used:
* firmware.json: innovaphone device firmware
* apps.json: Apps for the App Platform
* software.json: contains software for DECT handsets
** just IP64 and IP65 are used and supported
* phoneplatform.json: contains the phone platform image for e.g. the IP270

You can either use the standard innovaphone App Store for these files or your own local webserver. 

==== Update jobs ====
You can configure several update jobs with different categories to organize your updates. 
Update jobs are always sequentially processed and inside one update job, just '''20''' devices are updated at the same time.

==== Device update check after the update job has been already executed====
If a device goes online, the newest suitable update job is searched for this device (depending on the categories). 
If an update job is found, the update is just performed, if there has been '''no''' successfull update for this device in this job before and the version does not match (simply string compare).

====Update errors====
If an update fails, the Devices App shows an error. You may have to enable further tracing on the updated device itself to find out the reason of the failure. 
 
* on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0 module and take a look at the events which may already tell you the reason
* on an App Platform, enable the App and HTTP Client trace flag on the manager

An update job is retried '''two''' times if updates inside this job failed. The retry is done '''ten''' minutes after the update job finished previously.

====innovaphone myApps====
The path to the App Store and the used innovaphone myApps version is updated to the version of the gateway on gateways with an enabled PBX after a successfull update. 
This configuration can be found [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:PBX/Config/myApps here]

Inside the configuration on an update job, the flag "Do not update myApps launcher software" disables the update of the innovaphone myApps version inside PBXes.

====DECT handsets====
If you check the update DECT handsets checkmark, all DECT devices will be configured to rollout updates to DECT handsets. 
See [[{{NAMESPACE}}:Concept_App_Service_Devices#Supported_DECT_handsets | Supported DECT handsets]].

The DECT handset firmware will be searched inside the configured software.json.

=== Backups ===
The Devices App can be used to backup the configuration and data of Apps and devices. 

====Webserver requirements====
Backups are stored on a webserver with or without Digest/Basic authentication and with the '''webdav PUT''' method.

====Backup jobs====
Backup jobs are executed sequentially. Inside one backup job, just '''20''' backups are performed at the same time.

====Phones or gateways====
The configuration file is stored. Therefor the Devices App tells the device to store the configuration with a !mod cmd UP0 /sync prot URL.

====Apps on an App Platform====
The databases of all existing instances and the manager are stored. 
Each installed App Service can have multiple instances and each App instance has its own database. 
A database contains '''both''' configuration and data of an App instance! 
The manager database contains the webserver certificate and further manager related configuration settings.

The Devices App establishes a websocket connection to the manager and tells the manager where to store the backups. 
The manager on the backuped App Platform itself performs the HTTP requests to store the files.

====Backup errors====
If a backup fails, the Devices App shows an error. You may have to enable further tracing on the backuped device itself to find out the reason of the failure.

* on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0
* on an App Platform, enable the App and HTTP Client trace flag on the manager

=== Restore ===
====Phones or gateways====
Just as always under [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Administration/Upload/Config Upload Config].

====Apps====
The App Service itself has to be installed on the App Platform prior restoring of a single instance. 
The restoring is done in the Manager App on the App Platform itself. 
The intance settings, the configuration and data are restored in a single process.

=== Device Configurations ===

You can define several device configurations. These configurations are either applied to all devices inside this domain or to selected categories. 
Configurations are applied on creation and on every reconnect of a matching device.

==== Transfer checkmarks ====

Some configuration options have a specific checkmark to enable the transfer of the option. 
 
* Checkmark disabled:
** configuration option field(s) are disabled
** option values are '''not''' transferred at all
* Checkmark enabled:
** configuration option field(s) are enabled
** option values are transferred, even if field values are empty

==== Expert configuration ====

The expert configuration can be used to configure different settings which are not available inside the other device configurations. 
You can use the standard syntax of an update server script (see [[ {{NAMESPACE}}:Concept_Update_Server | Concept Update Server ]] for a general overview and the section on [[Howto:PHP_based_Update_Server_V2#Hints_for_writing_your_update_snippets | Hints for writing your update snippets ]] (note that the remainder of this article relates to the now deprecated old mechanism, so please disregard the rest)). 
 
Some hints:
* the expert configuration is just executed once after a device restarted and on change of the expert configuration itself
* the expert configuration is executed after all other device configuration types, so that you can override changes
* to make configuration changes effective, you may also need to issue a final ''config write'', ''config activate'' and ''iresetn'' command (see the [[ {{NAMESPACE}}:Concept_Update_Server#Check_command | ''check'' command]] for details)
* some commands shouldn't be used inside the script:
** [[ {{NAMESPACE}}:Concept_Update_Server#Times_command |''times'']]: since the expert configuration is executed only once after a reboot of the device and when changes are made, it does not make sense to use the ''times'' command
** [[ {{NAMESPACE}}:Concept_Update_Server#Prot_command |''prot'']]|[[ {{NAMESPACE}}:Concept_Update_Server#Boot_command |''boot'']]: use an update job instead
** [[ {{NAMESPACE}}:Concept_Update_Server#Scfg_command |''scfg'']]: use a backup job instead
** [[Howto:PHP_based_Update_Server_V2#Using_vars_create|''vars create'']]: this cmd will always raise the ''reset needed condition'' and the aforementioned ''iresetn'' command would always execute therefore. As a result, the devices would enter a boot loop. Be sure to avoid this using an appropriate [[ {{NAMESPACE}}:Concept_Update_Server#Check_command |''check'' command ]] and update its ''<serial>'' properly whenever the expert configuration is changed

==== Certificates configuration ====
You can use this configuration to rollout certificates to the trust list of your devices. 

* Manual upload certificates.
* Configure up to five URLs which are polled every 24 hours. They must return files with PEM formatted public keys (one or more) which are then rolled out.
** certificates are just rolled out if differences are determined, so if URLs are polled and no changes are detected, certificates are not rolled out again. Changes are detected by fingerprint comparison of each embedded certificate
** if a device restarts, the configuration is applied again. Just the fingerprints of the device trust list are checked against the configuration trust list and just on differences, certificates are rolled out again
* Configure https://download.innovaphone.com/certificates/innovaphone.pem to always have the innovaphone public keys in your trust list (e.g. used for our push service).
* Configure https://download.innovaphone.com/certificates/ca.pem to always have the innovaphone Device Certification Authority certificates in your trust list.
* Configure https://download.innovaphone.com/certificates/ca-unverified.pem to always have the innovaphone Unverified Device Certification Authority certificates in your trust list.
** The Unverified CA is used for non hardware devices, e.g. IPVAs, which are not shipped with an official innovaphone Device Certification Authority certificate, as innovaphone has no control over the serial number here.

Using this configuration, the trust list can only be managed through ''Devices'' because it is cleared before each rollout.

==== DECT Handsets ====

This configuration can be used to configure specific options like language, voicemail number etc. for DECT handsets. 
 
* all DECT devices like IP1202, IP1203 etc. will receive this configuration (of course just if the configured categories match)
* Devices configures a URL like https://domain.com/domain.com/devices/parameters/id.xml on the specific DEVMANBW module.
* This file is then polled by the basestations and the read values are transfered to the DECT handsets.
* see [[{{NAMESPACE}}:IP1202/IP1203_DECT_System#Configuration_of_Handset_parameters]]

See [[{{NAMESPACE}}:Concept_App_Service_Devices#Supported_DECT_handsets | Supported DECT handsets]].

=== Software rental ===
Regarding the Software Rental program and the Payment Method, please refer to:
* [[{{NAMESPACE}}:Concept_Software_Rental|Concept Software Rental]]

Software rental can be done for innovaphone Cloud installations or for software, which operates on the customer premisis. This could eventually be customer owned hardware or a privat virtual machine, managed by the customer.

==== Hardware licenses ====
Hardware licenses have to be bound on the specific device in my.innovaphone itself and currently can't be handled within the Devices App itself. So you also need to download the licenses from my.innovaphone and upload them on the device with the already known methods.

===== Hardware licenses with software rental =====
If your device has software rental licenses, you can bind hardware licenses within my.innovaphone in the software rental project itself.

===== Hardware licenses without software rental =====
If your device does not have software rental licenses, you should bind hardware licenses in a separate non rental project in my.innovaphone.

==== innovaphone Cloud ====
Inside the innovaphone Cloud, you just have to upload your activation keys with iSCs to add licenses to one or more gateways. 

==== Email expiry notifications ====
You will receive an email notification if the rental of a project expires. This notification will be sent '''seven''' weeks before the expiry and then once a week until the rental expires. 
You can configure one or more email recipients in the domain settings. 
If no email address is configured, the email address of the logged in user account is used.

==== History ====
You can download the history in the Devices App. You'll get a CSV file (semicolon separated). The date and number format depends on the selected language in the UI. 
There is also an API available for automated downloas, which is described [[ {{NAMESPACE}}:Concept_App_Service_Devices#API_to_download_rental_history|here ]].

====Own installation====
Inside your own installation, you have to register a new my.innovaphone account or you can use an existing account inside the Devices App. 
One domain inside Devices belongs to one project inside your my.innovaphone company, so you can handle multiple domains with one my.innovaphone account.

====Technical aspects====
A new rental expiration date is calculated on each license or balance change in the domain. 
So after each change new licenses with a new date are transfered to the gateways and also stored in the Devices App itself. 
If the rental expires, the gateway reboots and the licenses are not available anymore. 
The licenses are also transfered after each reconnect of a gateway to the Devices App. 
 
For license and balance changes, the Devices App must be online and have access to my.innovaphone.com!

====Usage====
You have to add (use the + symbol) a PBX and select all licenses you want to rent. 
Use the '''apply''' button to really bind these licenses. Without usage of the apply button, you can just see a precalculation of the iSCs/month and the rental end date, but nothing is really charged from your balance.

===Change of IP address/DNS name in PBX object===
If the IP address or DNS name inside the PBX object of the Devices App changes, all currently connected clients get a new Devices Registration URL and also all clients, which connect afterwards with the old host name.

== Appendix ==
=== Sample firmware.json ===
<code type="javascript">
{
"devices": [
{ "id": "IP0010", "versions": [ "13r1" ] },
{ "id": "IP0011", "versions": [ "13r1" ] },
{ "id": "IP101", "versions": [ "13r1" ] },
{ "id": "IP102", "versions": [ "13r1" ] },
{ "id": "IP1060", "versions": [ "13r1" ] },
{ "id": "IP110", "versions": [ "13r1" ] },
{ "id": "IP110A", "versions": [ "13r1" ] },
{ "id": "IP111", "versions": [ "13r1" ] },
{ "id": "IP112", "versions": [ "13r1" ] },
{ "id": "IP1130", "versions": [ "13r1" ] },
{ "id": "IP1260", "versions": [ "13r1" ] },
{ "id": "IP150", "versions": [ "13r1" ] },
{ "id": "IP2000", "versions": [ "13r1" ] },
{ "id": "IP200A", "versions": [ "13r1" ] },
{ "id": "IP22", "versions": [ "13r1" ] },
{ "id": "IP222", "versions": [ "13r1" ] },
{ "id": "IP230", "versions": [ "13r1" ] },
{ "id": "IP232", "versions": [ "13r1" ] },
{ "id": "IP24", "versions": [ "13r1" ] },
{ "id": "IP240", "versions": [ "13r1" ] },
{ "id": "IP241", "versions": [ "13r1" ] },
{ "id": "IP29", "versions": [ "13r1" ] },
{ "id": "IP3010", "versions": [ "13r1" ] },
{ "id": "IP3011", "versions": [ "13r1" ] },
{ "id": "IP302", "versions": [ "13r1" ] },
{ "id": "IP305", "versions": [ "13r1" ] },
{ "id": "IP311", "versions": [ "13r1" ] },
{ "id": "IP411", "versions": [ "13r1" ] },
{ "id": "IP6000", "versions": [ "13r1" ] },
{ "id": "IP6010", "versions": [ "13r1" ] },
{ "id": "IP800", "versions": [ "13r1" ] },
{ "id": "IP810", "versions": [ "13r1" ] },
{ "id": "IP811", "versions": [ "13r1" ] },
{ "id": "IPVA", "versions": [ "13r1" ] }
],
"versions": [
{ "id": "13r1", "build": "131705", "text": "13r1 dvl [131705]", "wiki": "" }
]
}
</code>

=== Sample apps.json ===
<code type="javascript">
{
"apps": [
{
"id": "apidemo",
"folder": "apidemo",
"binary": "apidemo",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "Apidemo",
"description": "The Apidemo"
},
{
"id": "appstore",
"folder": "appstore",
"binary": "appstore",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "AppStore",
"description": "AppStore"
}
]
}
</code>

=== Sample software.json ===
<code type="javascript">
{
"software": [
{
"id": "myappsandroid",
"folder": "myappsandroid",
"binary": "myapps.apk",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "myApps Android",
"description": "myApps for Android"
},
{
"id": "myappswindows",
"folder": "myappswindows",
"binary": "myAppsSetup.msi",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "myApps Windows",
"description": "myApps for Windows"
}
]
}
</code>

=== Sample phoneplatform.json ===
<code type="javascript">
{
"phoneplatforms": [
{
"id": "arm64",
"text": "Phone Platform",
"file": "phone-platform.img",
"folder": "yocto2",
"version": "2063"
}
],
"devices": [
{
"id": "IP270",
"phoneplatforms": [
"arm64"
]
}
]
}
</code>

=== API to download rental history ===

You can download the history as a UTF-8 CSV file with simple '''HTTP GET''' requests with '''digest''' authentication. 
The CSV file uses the semicolon as delimiter. 
 
The URL to download the history is e.g.: 
'''<code>https://mydomain.com/mydomain.com/devices/csvapi?...</code>'''

You can find this path by editing the instance in the AP manager.
In the listed paths, you'll find something which ends with csvapi

In the innovaphone Cloud environment, the URL can be retrieved by taking a look at the Devices App object inside the cloud PBX and replacing the ending '''innovaphone-devices''' with '''csvapi''' inside the App URL, so it looks e.g. like this:

https://cloud-apps0.innovaphone.com/cloud.innovaphone.com/devices/csvapi

====CSV columns====
Most columns should be self explaining, but the column '''invoice reference''' refers to a value which you can configure manually in the domain settings in the Devices App!

====Digest authentication====
You can login with two different username/password combinations, while the domain is the digest username:

* If you use the domain and password of your Devices App instance inside the AP Manager, you have automatically access to all domains. 
* If you use the domain name of any domain as digest username and the configured domain password, you'll have access to this domain and all domains to which this domain has access to

====Query parameters====
The following query parameters can be used (don't forget to URL encode the parameter values, if neccessary!):
* all: if '''1''' or '''true''', the history is queried for all domains where the digest user has access to
* domain: required, if ''all'' is not set
* lang: the output language of the CSV file, which also controls date and number formats, e.g. '''en''', '''de''', ...
* tz: the timezone for dates, e.g. '''Europe/Berlin'''
* type: two types are available:
** '''history''': history which contains changes
** '''overview''': a monthly overview with the iSC costs at the first of the last months
* from: unix timestamp (UTC) in milliseconds, ignored for type=overview
* to: unix timestamp (UTC) in milliseconds, ignored for type=overview

====Example requests====
* <code>https://mydomain.com/mydomain.com/devices/csvapi?domain=mydomain.com&type=overview&lang=en&tz=Europe%2FBerlin</code>
* <code>https://mydomain.com/mydomain.com/devices/csvapi?domain=mydomain.com&type=history&lang=en&tz=Europe%2FBerlin&from=1601903431000&to=1601903385000</code>
* <code>https://mydomain.com/mydomain.com/devices/csvapi?all=1&type=overview&lang=en&tz=Europe%2FBerlin</code>

=== Supported DECT handsets ===

The following handsets are supported for update jobs and the DECT handsets configuration:

* IP64
* IP65
* D81
* D83

== Known issues ==

===SoftwarePhone===
The Devices App is not meant to be used with the windows SoftwarPhone standalone installation.

== Related Articles ==
* [[Howto:Software_Rental]]

Reference15r1:Concept App Service Devices

2025-10-14T13:14:49Z

Dde: /* Certificates configuration */

[[Category:Concept|Apps]]
The App Service Devices is an App Service which can be installed on an innovaphone App Platform. It is used to administrate the innovaphone devices which belong to the whole installation.
== Applies To ==

* innovaphone PBX from version 13r1

== Apps ==

=== Devices App (innovaphone-devices) ===
This is the standard UI App for Devices.

Parameters:

;Websocket: to publish the com.innovaphone.devicesui-API, which can be used to link directly to devices (which is done e.g. inside the Events app)

=== Devices API (innovaphone-devices-api) ===
This is a hidden App, which provides the Devices API (com.innovaphone.devices). This API can be used to find and communicate with devices which are registered to the Devices App.

Additionally it acts as a provider of the Search API (com.innovaphone.search). So you can find devices and domains in other apps like the Search App.

Parameters:

;Hidden: DevicesApi must be a hidden App
;Websocket: to get the URL of the Devices App itself which is used for provisioning

== PBX Manager Plugins ==

=== Devices ===

With the Devices plugin App objects can be created, edited and deleted for Devices and the Devices API on the PBX.

== Concepts ==
All innovaphone hard phones and gateways starting from version 13r1 can establish a registration inside the Devices App and therefor administrative tasks can be performed through the App.

=== Domains ===

In a hosted environment, it might be needed to add multiple domains to the Devices App. 
After the initial installation of Devices through Install, you have administrative rights and can add more domains.

==== Administrative rights ====
You have administrative rights if the configured PBX App object for Devices uses the password of the instance which is configured in the Manager App and the PBX uses the same domain as this instance.

==== Domain local rights ====
You have just rights to a certain domain if the configured PBX App object for Devices uses the domain password which can be configured in Devices for each domain and the PBX uses the same domain name as configured in Devices.

==== Assign rights to other domains ====
Domains can gain access to other domains by configuring these access rights in the Devices App.

==== Deploy passwords and access rights ====
During install, a domain is created inside the Devices App. There is a checkmark Deploy the domain password on all devices which is set by default and which is the same as the administrative password.
If you change the domain password, all passwords on all administrative devices and app platforms which are connected to this domain will be also changed. 
Since 13r2sr25/13r3sr7/14rx: devices which are auto provisioned or provisioned through the Profile/Users Admin App will get a random password instead of the domain password.
If you add a phone device manually to a domain inside the Devices App, this phone device will also get a random password. Other device types added manually or devices added with a provisioning code which has been created within the Devices App directly, will get the domain password instead. 
 
This will also set the manager password and the SSH passwords of App Platforms. 
 
The clear text random passwords can be requested and viewed in the settings of a device in the Devices App.

Attention: If you untick the '''Deploy administrative devices passwords''' checkmark, the password won't be deployed anymore, but also not reconfigured to the default password!

Attention: After each reconnect of a client, the password will be deployed again.
This means, if the checkmark is set and you set another password somewhere else (e.g. under General::Admin),
this password will be just valid until the next reboot or reconnect to the Devices App!

;Create new random passwords
You can rollout new random passwords by unticking the '''Deploy administrative devices passwords''' checkmark and ticking it again. 

;Devices with multiple domains (Cloud)
In a hosted environment, you can use the Devices App with multiple domains. The corresponding instance of Devices has a configured domain and an instance password set inside the manager. 

The hosting PBX has a domain inside Devices with a specific password. 
If this domain name matches the instance domain of the Devices instance and the password matches either the instance password or the domain password, you will be logged in as admin and have access to all domains. 

Each newly created domain has its own password inside Devices. If you create an App Object inside a PBX with this domain and the password of this domain (inside Devices), you will just have access to this single domain. 

Devices also has the possibility to grant access to other domains for a specific domain.

=== Categories ===

There are two types of categories:
* provisioning category: used for device configurations and provisioning
* standard category: used for update/backup jobs and device management

Each device can have just a '''single''' provisioning category, as it receives it's configuration by all configured device configurations for this provisioning category.

In addition, a provisioning category, which is used inside an analogue phone/phone device configuration '''cannot''' be used to provision a gateway.

=== Device connections ===
The Devices registration is done through a websocket connection to the webserver of the App Platform and the Devices instance (standard HTTP/s port). 
The URL used can be configured manually under [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:General/Devices_Registration Devices Registration] or through a new provisioning mechanism. 
 
A binary protocol is used to transfer information between the device and the devices App. The MAC address is the unique key to identify a device. 
 
If a device is added to a domain in Devices, the device gets a unique random password. Without such a password, a device shows up as '''unassigned''' in the Devices app.
This is also the case after a long reset or when the device lost its configuration. 
 
In such a case, the device has to be manually added again to a domain or it has to be provisioned again.

If a device is not assigned to a domain or provisioning category, it won't receive any configurations.

==== Devices Registrations ====
See [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:General/Devices_Registration Devices Registration]

==== Second Devices Registration URL ====

The firmware has a second SYSCLIENT2 module, which can be configured to point to a different Devices instance and the AP Manager also has a second Devices Registration URL. 
 
If you use this configuration option, you should take care and consider:

* if the Devices domain from the second configuration provides a password for all devices, the password is ignored, as it would lead to inconsistend passwords otherwise (from 13r1 SR12 on)
* the Devices domain from the second configuration should not provide Devices Configurations or Update Jobs as these might collide with configurations from the first Devices instance!

Generally, only one of the two ''Devices'' App instances connected to the device must apply changes to the device.

We strongly discourage the usage of this second configuration option due to unexpected behaviour if incorrectly used!
Never use the second URL if you use software or hardware rental!

==== Device information ====

The following data is transferred:
* MAC address
* device type (e.g. IPVA, AppPlatform, IP112)
* IP addresses (IPv4, IPv6)
* version (not searchable)

You can also search for this data inside the devices tab in the App.


=== Provisioning ===
Devices can be added by provisioning (both phones and gateways).
The standard online provisioning looks like this:
* a user or administrator creates a provisioning code in the Devices or Users App (this stores the Devices URL on the provisioning server side)
* a device with 13r1 or newer is connected to the network after a long reset
* the provisioning code has to be entered within one hour (after one hour, the Update URL isn't polled anymore)
* the device sends this code to config.innovaphone.com and retrieves the Devices URL
* the device connects to the Devices URL and is added to the domain where the code has been created

There is also an [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Offline_Provisioning offline provisioning mode]. 
There is also an [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Provisioning#Automatic_provisioning automatic provisioning mode].

Note: provisioning is cancelled if the device already belongs to another domain in the same Devices instance! This prevents the unauthorized move of a device between different domains.

==== Devices Registration URL ====

The Devices Registration URL which is set through the provisioning process, always starts with '''wss'''. This is not dependent anymore on the App URL which is configured inside the PBX Devices App object.

=== Updates ===
The Devices App can be used to rollout updates. 

==== JSON files ====
The update files have to be acccessible on a webserver without authentication and four json files are used:
* firmware.json: innovaphone device firmware
* apps.json: Apps for the App Platform
* software.json: contains software for DECT handsets
** just IP64 and IP65 are used and supported
* phoneplatform.json: contains the phone platform image for e.g. the IP270

You can either use the standard innovaphone App Store for these files or your own local webserver. 

==== Update jobs ====
You can configure several update jobs with different categories to organize your updates. 
Update jobs are always sequentially processed and inside one update job, just '''20''' devices are updated at the same time.

==== Device update check after the update job has been already executed====
If a device goes online, the newest suitable update job is searched for this device (depending on the categories). 
If an update job is found, the update is just performed, if there has been '''no''' successfull update for this device in this job before and the version does not match (simply string compare).

====Update errors====
If an update fails, the Devices App shows an error. You may have to enable further tracing on the updated device itself to find out the reason of the failure. 
 
* on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0 module and take a look at the events which may already tell you the reason
* on an App Platform, enable the App and HTTP Client trace flag on the manager

An update job is retried '''two''' times if updates inside this job failed. The retry is done '''ten''' minutes after the update job finished previously.

====innovaphone myApps====
The path to the App Store and the used innovaphone myApps version is updated to the version of the gateway on gateways with an enabled PBX after a successfull update. 
This configuration can be found [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:PBX/Config/myApps here]

Inside the configuration on an update job, the flag "Do not update myApps launcher software" disables the update of the innovaphone myApps version inside PBXes.

====DECT handsets====
If you check the update DECT handsets checkmark, all DECT devices will be configured to rollout updates to DECT handsets. 
See [[{{NAMESPACE}}:Concept_App_Service_Devices#Supported_DECT_handsets | Supported DECT handsets]].

The DECT handset firmware will be searched inside the configured software.json.

=== Backups ===
The Devices App can be used to backup the configuration and data of Apps and devices. 

====Webserver requirements====
Backups are stored on a webserver with or without Digest/Basic authentication and with the '''webdav PUT''' method.

====Backup jobs====
Backup jobs are executed sequentially. Inside one backup job, just '''20''' backups are performed at the same time.

====Phones or gateways====
The configuration file is stored. Therefor the Devices App tells the device to store the configuration with a !mod cmd UP0 /sync prot URL.

====Apps on an App Platform====
The databases of all existing instances and the manager are stored. 
Each installed App Service can have multiple instances and each App instance has its own database. 
A database contains '''both''' configuration and data of an App instance! 
The manager database contains the webserver certificate and further manager related configuration settings.

The Devices App establishes a websocket connection to the manager and tells the manager where to store the backups. 
The manager on the backuped App Platform itself performs the HTTP requests to store the files.

====Backup errors====
If a backup fails, the Devices App shows an error. You may have to enable further tracing on the backuped device itself to find out the reason of the failure.

* on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0
* on an App Platform, enable the App and HTTP Client trace flag on the manager

=== Restore ===
====Phones or gateways====
Just as always under [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Administration/Upload/Config Upload Config].

====Apps====
The App Service itself has to be installed on the App Platform prior restoring of a single instance. 
The restoring is done in the Manager App on the App Platform itself. 
The intance settings, the configuration and data are restored in a single process.

=== Device Configurations ===

You can define several device configurations. These configurations are either applied to all devices inside this domain or to selected categories. 
Configurations are applied on creation and on every reconnect of a matching device.

==== Transfer checkmarks ====

Some configuration options have a specific checkmark to enable the transfer of the option. 
 
* Checkmark disabled:
** configuration option field(s) are disabled
** option values are '''not''' transferred at all
* Checkmark enabled:
** configuration option field(s) are enabled
** option values are transferred, even if field values are empty

==== Expert configuration ====

The expert configuration can be used to configure different settings which are not available inside the other device configurations. 
You can use the standard syntax of an update server script (see [[ {{NAMESPACE}}:Concept_Update_Server | Concept Update Server ]] for a general overview and the section on [[Howto:PHP_based_Update_Server_V2#Hints_for_writing_your_update_snippets | Hints for writing your update snippets ]] (note that the remainder of this article relates to the now deprecated old mechanism, so please disregard the rest)). 
 
Some hints:
* the expert configuration is just executed once after a device restarted and on change of the expert configuration itself
* the expert configuration is executed after all other device configuration types, so that you can override changes
* to make configuration changes effective, you may also need to issue a final ''config write'', ''config activate'' and ''iresetn'' command (see the [[ {{NAMESPACE}}:Concept_Update_Server#Check_command | ''check'' command]] for details)
* some commands shouldn't be used inside the script:
** [[ {{NAMESPACE}}:Concept_Update_Server#Times_command |''times'']]: since the expert configuration is executed only once after a reboot of the device and when changes are made, it does not make sense to use the ''times'' command
** [[ {{NAMESPACE}}:Concept_Update_Server#Prot_command |''prot'']]|[[ {{NAMESPACE}}:Concept_Update_Server#Boot_command |''boot'']]: use an update job instead
** [[ {{NAMESPACE}}:Concept_Update_Server#Scfg_command |''scfg'']]: use a backup job instead
** [[Howto:PHP_based_Update_Server_V2#Using_vars_create|''vars create'']]: this cmd will always raise the ''reset needed condition'' and the aforementioned ''iresetn'' command would always execute therefore. As a result, the devices would enter a boot loop. Be sure to avoid this using an appropriate [[ {{NAMESPACE}}:Concept_Update_Server#Check_command |''check'' command ]] and update its ''<serial>'' properly whenever the expert configuration is changed

==== Certificates configuration ====
You can use this configuration to rollout certificates to the trust list of your devices. 

* Manual upload certificates.
* Configure up to five URLs which are polled every 24 hours. They must return files with PEM formatted public keys (one or more) which are then rolled out.
** certificates are just rolled out if differences are determined, so if URLs are polled and no changes are detected, certificates are not rolled out again
** if a device restarts, the configuration is applied again. Just the fingerprints of the device trust list are checked against the configuration trust list and just on differences, certificates are rolled out again
* Configure https://download.innovaphone.com/certificates/innovaphone.pem to always have the innovaphone public keys in your trust list (e.g. used for our push service).
* Configure https://download.innovaphone.com/certificates/ca.pem to always have the innovaphone Device Certification Authority certificates in your trust list.
* Configure https://download.innovaphone.com/certificates/ca-unverified.pem to always have the innovaphone Unverified Device Certification Authority certificates in your trust list.
** The Unverified CA is used for non hardware devices, e.g. IPVAs, which are not shipped with an official innovaphone Device Certification Authority certificate, as innovaphone has no control over the serial number here.

Using this configuration, the trust list can only be managed through ''Devices'' because it is cleared before each rollout.

==== DECT Handsets ====

This configuration can be used to configure specific options like language, voicemail number etc. for DECT handsets. 
 
* all DECT devices like IP1202, IP1203 etc. will receive this configuration (of course just if the configured categories match)
* Devices configures a URL like https://domain.com/domain.com/devices/parameters/id.xml on the specific DEVMANBW module.
* This file is then polled by the basestations and the read values are transfered to the DECT handsets.
* see [[{{NAMESPACE}}:IP1202/IP1203_DECT_System#Configuration_of_Handset_parameters]]

See [[{{NAMESPACE}}:Concept_App_Service_Devices#Supported_DECT_handsets | Supported DECT handsets]].

=== Software rental ===
Regarding the Software Rental program and the Payment Method, please refer to:
* [[{{NAMESPACE}}:Concept_Software_Rental|Concept Software Rental]]

Software rental can be done for innovaphone Cloud installations or for software, which operates on the customer premisis. This could eventually be customer owned hardware or a privat virtual machine, managed by the customer.

==== Hardware licenses ====
Hardware licenses have to be bound on the specific device in my.innovaphone itself and currently can't be handled within the Devices App itself. So you also need to download the licenses from my.innovaphone and upload them on the device with the already known methods.

===== Hardware licenses with software rental =====
If your device has software rental licenses, you can bind hardware licenses within my.innovaphone in the software rental project itself.

===== Hardware licenses without software rental =====
If your device does not have software rental licenses, you should bind hardware licenses in a separate non rental project in my.innovaphone.

==== innovaphone Cloud ====
Inside the innovaphone Cloud, you just have to upload your activation keys with iSCs to add licenses to one or more gateways. 

==== Email expiry notifications ====
You will receive an email notification if the rental of a project expires. This notification will be sent '''seven''' weeks before the expiry and then once a week until the rental expires. 
You can configure one or more email recipients in the domain settings. 
If no email address is configured, the email address of the logged in user account is used.

==== History ====
You can download the history in the Devices App. You'll get a CSV file (semicolon separated). The date and number format depends on the selected language in the UI. 
There is also an API available for automated downloas, which is described [[ {{NAMESPACE}}:Concept_App_Service_Devices#API_to_download_rental_history|here ]].

====Own installation====
Inside your own installation, you have to register a new my.innovaphone account or you can use an existing account inside the Devices App. 
One domain inside Devices belongs to one project inside your my.innovaphone company, so you can handle multiple domains with one my.innovaphone account.

====Technical aspects====
A new rental expiration date is calculated on each license or balance change in the domain. 
So after each change new licenses with a new date are transfered to the gateways and also stored in the Devices App itself. 
If the rental expires, the gateway reboots and the licenses are not available anymore. 
The licenses are also transfered after each reconnect of a gateway to the Devices App. 
 
For license and balance changes, the Devices App must be online and have access to my.innovaphone.com!

====Usage====
You have to add (use the + symbol) a PBX and select all licenses you want to rent. 
Use the '''apply''' button to really bind these licenses. Without usage of the apply button, you can just see a precalculation of the iSCs/month and the rental end date, but nothing is really charged from your balance.

===Change of IP address/DNS name in PBX object===
If the IP address or DNS name inside the PBX object of the Devices App changes, all currently connected clients get a new Devices Registration URL and also all clients, which connect afterwards with the old host name.

== Appendix ==
=== Sample firmware.json ===
<code type="javascript">
{
"devices": [
{ "id": "IP0010", "versions": [ "13r1" ] },
{ "id": "IP0011", "versions": [ "13r1" ] },
{ "id": "IP101", "versions": [ "13r1" ] },
{ "id": "IP102", "versions": [ "13r1" ] },
{ "id": "IP1060", "versions": [ "13r1" ] },
{ "id": "IP110", "versions": [ "13r1" ] },
{ "id": "IP110A", "versions": [ "13r1" ] },
{ "id": "IP111", "versions": [ "13r1" ] },
{ "id": "IP112", "versions": [ "13r1" ] },
{ "id": "IP1130", "versions": [ "13r1" ] },
{ "id": "IP1260", "versions": [ "13r1" ] },
{ "id": "IP150", "versions": [ "13r1" ] },
{ "id": "IP2000", "versions": [ "13r1" ] },
{ "id": "IP200A", "versions": [ "13r1" ] },
{ "id": "IP22", "versions": [ "13r1" ] },
{ "id": "IP222", "versions": [ "13r1" ] },
{ "id": "IP230", "versions": [ "13r1" ] },
{ "id": "IP232", "versions": [ "13r1" ] },
{ "id": "IP24", "versions": [ "13r1" ] },
{ "id": "IP240", "versions": [ "13r1" ] },
{ "id": "IP241", "versions": [ "13r1" ] },
{ "id": "IP29", "versions": [ "13r1" ] },
{ "id": "IP3010", "versions": [ "13r1" ] },
{ "id": "IP3011", "versions": [ "13r1" ] },
{ "id": "IP302", "versions": [ "13r1" ] },
{ "id": "IP305", "versions": [ "13r1" ] },
{ "id": "IP311", "versions": [ "13r1" ] },
{ "id": "IP411", "versions": [ "13r1" ] },
{ "id": "IP6000", "versions": [ "13r1" ] },
{ "id": "IP6010", "versions": [ "13r1" ] },
{ "id": "IP800", "versions": [ "13r1" ] },
{ "id": "IP810", "versions": [ "13r1" ] },
{ "id": "IP811", "versions": [ "13r1" ] },
{ "id": "IPVA", "versions": [ "13r1" ] }
],
"versions": [
{ "id": "13r1", "build": "131705", "text": "13r1 dvl [131705]", "wiki": "" }
]
}
</code>

=== Sample apps.json ===
<code type="javascript">
{
"apps": [
{
"id": "apidemo",
"folder": "apidemo",
"binary": "apidemo",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "Apidemo",
"description": "The Apidemo"
},
{
"id": "appstore",
"folder": "appstore",
"binary": "appstore",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "AppStore",
"description": "AppStore"
}
]
}
</code>

=== Sample software.json ===
<code type="javascript">
{
"software": [
{
"id": "myappsandroid",
"folder": "myappsandroid",
"binary": "myapps.apk",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "myApps Android",
"description": "myApps for Android"
},
{
"id": "myappswindows",
"folder": "myappswindows",
"binary": "myAppsSetup.msi",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "myApps Windows",
"description": "myApps for Windows"
}
]
}
</code>

=== Sample phoneplatform.json ===
<code type="javascript">
{
"phoneplatforms": [
{
"id": "arm64",
"text": "Phone Platform",
"file": "phone-platform.img",
"folder": "yocto2",
"version": "2063"
}
],
"devices": [
{
"id": "IP270",
"phoneplatforms": [
"arm64"
]
}
]
}
</code>

=== API to download rental history ===

You can download the history as a UTF-8 CSV file with simple '''HTTP GET''' requests with '''digest''' authentication. 
The CSV file uses the semicolon as delimiter. 
 
The URL to download the history is e.g.: 
'''<code>https://mydomain.com/mydomain.com/devices/csvapi?...</code>'''

You can find this path by editing the instance in the AP manager.
In the listed paths, you'll find something which ends with csvapi

In the innovaphone Cloud environment, the URL can be retrieved by taking a look at the Devices App object inside the cloud PBX and replacing the ending '''innovaphone-devices''' with '''csvapi''' inside the App URL, so it looks e.g. like this:

https://cloud-apps0.innovaphone.com/cloud.innovaphone.com/devices/csvapi

====CSV columns====
Most columns should be self explaining, but the column '''invoice reference''' refers to a value which you can configure manually in the domain settings in the Devices App!

====Digest authentication====
You can login with two different username/password combinations, while the domain is the digest username:

* If you use the domain and password of your Devices App instance inside the AP Manager, you have automatically access to all domains. 
* If you use the domain name of any domain as digest username and the configured domain password, you'll have access to this domain and all domains to which this domain has access to

====Query parameters====
The following query parameters can be used (don't forget to URL encode the parameter values, if neccessary!):
* all: if '''1''' or '''true''', the history is queried for all domains where the digest user has access to
* domain: required, if ''all'' is not set
* lang: the output language of the CSV file, which also controls date and number formats, e.g. '''en''', '''de''', ...
* tz: the timezone for dates, e.g. '''Europe/Berlin'''
* type: two types are available:
** '''history''': history which contains changes
** '''overview''': a monthly overview with the iSC costs at the first of the last months
* from: unix timestamp (UTC) in milliseconds, ignored for type=overview
* to: unix timestamp (UTC) in milliseconds, ignored for type=overview

====Example requests====
* <code>https://mydomain.com/mydomain.com/devices/csvapi?domain=mydomain.com&type=overview&lang=en&tz=Europe%2FBerlin</code>
* <code>https://mydomain.com/mydomain.com/devices/csvapi?domain=mydomain.com&type=history&lang=en&tz=Europe%2FBerlin&from=1601903431000&to=1601903385000</code>
* <code>https://mydomain.com/mydomain.com/devices/csvapi?all=1&type=overview&lang=en&tz=Europe%2FBerlin</code>

=== Supported DECT handsets ===

The following handsets are supported for update jobs and the DECT handsets configuration:

* IP64
* IP65
* D81
* D83

== Known issues ==

===SoftwarePhone===
The Devices App is not meant to be used with the windows SoftwarPhone standalone installation.

== Related Articles ==
* [[Howto:Software_Rental]]

Reference14r2:Concept App Platform

2025-10-07T05:42:28Z

Dde: /* General */

= General =
* V13 uses [https://buildroot.org/ buildroot]
* this is an own (innovaphone) collection of packages
* For further information see: [https://buildroot.org/docs.html Buildroot Documentations]

== Requirements ==

* V13 or above
* Gateway (arm): IPx10 (with CF card) or IPx11 (with mSATA SSD)
* Gateway (arm64): IPx13 (with m2 SSD)
* Virtual (x86_64)
** HyperV with [https://docs.microsoft.com/de-de/windows-server/virtualization/hyper-v/deploy/upgrade-virtual-machine-version-in-hyper-v-on-windows-or-windows-server#supported-virtual-machine-configuration-versions VM-configuration Version] 6.2 (minimum: Windows 10 or Windows Server 2016)
** VMWare
** Proxmox/KVM/Qemu

== Default credentials ==

'''During INSTALL, the default passwords are replaced with the global Admin PW!'''
* SSH-Login with '''admin''' and '''ipapps'''
* root login with '''root''' and '''iplinux''' (the root login is not directly possible, you have to login as admin first and use the command ''su root'')
* manager App (web login) '''pwd'''

= App Platform - arm/arm64 (Gateway)=

* The installation image has a size of ~50MB. During installation, the following partitions are created<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 fat32: 200MB (contains ramdisk, rootfs and kernel)
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB

When comparing potential performance of the IPxx11 platform compared to the IPxx10 platform, there are some major differences:
* SSDs found in the xx11 are faster and more reliable than the CF found in the xx10
* the available RAM for the App Platform (as specified in column ''RAM for LAP (GB) out of RAM'' in chapter ''Technical data and recommended number of users supported'' of [[Howto:How to implement large PBXs#Technical data and recommended number of users supported|How to implement large PBXs]]) is factor 6 larger on the xx11 (1,536 GB) than on the xx10 (0,256 GB))
* the xx11 has gigabit Ethernet while the xx10 has 100Mbps Ethernet. The xx10 is therefore not well suited for Apps with larger network traffic, such as Recordings
* the CPU of the xx11 (although it runs on the same frequency) is roughly 20% faster than the xx10

While it is hard to predict the performance of the App Platform in a specific scenario, we see that in a real life environment an App Platform running on an xx11 platform can well support 150 users. The xx10 platform is estimated to support 120 users. Because CPU performance is the limiting factor, larger setups can be built based on the virtual machine platform (see [[#App services and multi-threading|App services and multi-threading]] below).

<references/>

= App Platform - x86-64 (Virtual Machine 64bit) =

* The default disk size is 16GB. It should be increased '''before''' the first start if needed!
* Multiple CPUs are supported, default is one CPU
* default RAM: 512MB
* static IP address, DNS, Gateway can be configured with the command '''setip''' on the console. Run '''setip --help''' to get a list of parameters. (Example: setip --addr=x.x.x.x --mask=x.x.x.x --gateway=x.x.x.x --dns1=x.x.x.x)
* If you have permission problems change to su user (Password is iplinux or your new admin password)
* To figure out your ip address you can use the command: ''ip address'' on the console.
* '''loadkeys de''' can be used to change to german keyboard layout (etc.)
* partitions<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 ext2: 350MB (contains ramdisk, rootfs and kernel)
*** the real partition format size is smaller but there is no need to monitor sda1 as sda1 won't grow during usage of the App Platform
*** sda1 is completely exchanged during an image update and its size might have changed but will never exceed these 350MB
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB
* VMWare Tools: Open VM Tools
* Qemu Guest Agent: installed since 110032
** The qemu guest agent can be configured in Proxmox with ''Virtio'' or ''ISA''. Before version 130012, you must use ISA, as Virtio was not supported with older versions.

<references/>

= Installation =
==ARM Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-armel.img'' image file.
* The installation runs without any further required step.

==ARM64 Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-arm64.img'' image file.
* The installation runs without any further required step.

==Virtual machine==

* Import the image into your server environment.
** Proxmox: follow this description here, just with the app-platform-ova.zip: https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Proxmox_VE
* Edit the disk size, if needed.
* Start the machine and wait until it reboots and starts again.
* Note: If you need to access an IP addresses available through a VPN connection from from inside the virtual machine, it could be that you need to set the network of your VM to NAT (and also add the URL for an IP to /etc/hosts)

[https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Configuration More Configuration Hints regarding VM Ware]

== Backup of the Apps ==

Each App Service can have multiple instances and each instance has its own database. The manager app itself also has its own database. 
There are no other files which need to be backuped. 
The standard way to backup the databases is through the Devices App [[{{NAMESPACE}}:Concept_App_Service_Devices#Backups]]. 
 
An alternate way is to use a command file which is similar to the command files from the firmware.

===Commands===
* '''times''' 0,12 # backup only at 0 or 12 o'clock
* '''backup-instances''' http://user:pw@ip/path/#I-#D.dump PUT
** PUT and POST are supported, all instances including the manager itself are saved
* '''backup-instance''' http://user:pw@ip/path/#I-#D.dump apidemo example.com PUT
** backup a single instance with instance name and instance domain
* '''backup-manager''' http://user:pw@ip/path/#I-#D.dump

===Hash parameters===
* #L App Platform label (neu), e.g. 10024
* #A App label (neu), e.g. 130004
* #I instance name (neu), e.g. reporting1
* #D instance domain (neu), e.g. innovaphone.com
* #m MAC address of the LAP, e.g. 00ab11eeff
* #d Current date and time (plain UTC without daylight saving and timezone adjustments) 20051010-170130
* #bn rolling backup index (n >=0 and <= 9, just one digit)
* ## escapes a hash mark

= App Platform Infrastructure and Concept =
== Webserver ==
The app platform includes a webserver that is highly optimized for handling many Websocket connections at a low memory footprint.
All apps use that webserver by registering for specific HTTP subpath. So they can all use the same HTTP/HTTPS ports - typically the standard ports.

=== Import Custom SSL Certificate ===
You have to upload a PEM Certificate with the following chain structure and without password encoding.

-----BEGIN CERTIFICATE-----
(certificate: eg. your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: eg. DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: eg. TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: eg. your_domain_name.key)
-----END RSA PRIVATE KEY-----

If you have problems generating the complete and correct certificate chain, you can use tools such as https://whatsmychaincert.com/ as an aid.
'''Please keep in mind that you never give away the private part of your key.'''

=== Known issues ===
*The app platform webserver can use only the default http/https ports 80/443.
*By design, there is no possibility to restore the default webserver certificate on the App Platform, if another certificate was once uploaded. 
**If nevertheless needed, you must login with Putty (see [[#How to retrieve files from the AP| Retrieve files]]) and execute these commands as root:
**''psql -d manager -c "DELETE FROM config WHERE name='webserverCertificate'"''
**''/etc/init.d/S92manager restart''
*The app platform webserver interprets URLs case-sensitive. In other words, <nowiki>http://<addr>/file.txt</nowiki> is not the same as <nowiki>http://<addr>/FILE.TXT</nowiki>

== Database ==
The app platform creates a database for each app instance with a given password. In the installer there will be used randomly generated passwords. You can set a new database password for every instance in the Application Platform.

The apps should store all data in that database. That makes sure that a consistent backup and restore of app instances can be done by the app platform manager.
In hosted scenarios, having separate databases for each instance also makes sure that the data of different customers are clearly separated and can easily be moved from one physical platform to another.

The default configuration decline database request from extern. If you need external access you can change the PGSQL configuration (as root) in the file ''/mnt/sda2/pgsql/pg_hba.conf''.
After editing pg_hba.conf, the database-service has to be restarted with the command <code>/etc/init.d/S50postgresql restart</code>
(Please think about it before you do it, because a better way is to create your own local app with local database access.)

You can find the official documentation for the pg_hba.conf here: https://www.postgresql.org/docs/14/auth-pg-hba-conf.html

Please note that you do this on your own responsibility, that it makes sense to create a backup of the original pg_hba.conf
and that you may break your database server if you do not know exactly what you do!

Sometimes the Apps are not proper working after this. You can wait a while until everything is working again or you go the hard way:
* stop the manager
** <code>/etc/init.d/S92manager stop</code>
* restart the database-service (maybe not really necessary, but makes a good feeling)
**<code>/etc/init.d/S50postgresql restart</code>
* start the manager
** <code>/etc/init.d/S92manager start</code>

=== Nightly database analyse ===

Every database is analysed at night to keep indexes in sync with the data. This triggers a ''vacuumdb -a -z'', which updates optimizer statistics, but does '''not''' shrink the physical size of the database. 
This must be done manually in the instance settings.

== App Platform Manager ==
The App Platform Manager is the central component of the App Platform. It does the following:
* Installing app services by downloading the binaries from an app store.
* Running and monitoring app services. If an app service crashes it is restarted, automatically.
* Management of app instances and providing them with the environment they need:
** A database
** A webserver path
** A password for authentication
* Backup and restore of app instances.
* Collecting debug information like tracing and crash dumps.
* System monitoring (CPU usage, memory usage, etc).

== App Services ==
App services are runned by the App Platform Manager. They implement an interface that is used by the manager to start, stop and configure app instances. Each service runs in a separate child process of the manager.

== App Instances ==
The actual functionality of an app service is provided by app instances. They run in the same process as the app service but have a distinct webserver path and their own database. There can be 0..n instances of an app service. Instances can optionally host (web) apps that can be opened in the myApps client.

Each instance of an App service has two passwords. The instance password itself and a database password. If you want to change it you must update the password on both sides. 
The instance password must match to the password in the corresponding PBX App objects, while one instance can have different App objects. 
The database password must be just known to the manager and not outside of the App Platform.

The ''Database name'' and ''Database user'' are both limited to a length of 63 characters. By default, the App Manager would create ''<domain>''_''<instance-name>'' as value for both. This is why it is recommended to use instance names so that length(name) + length(domain) is less than 63 characters. However, if this is not possible, you can manually shorten the suggested values (both must still be unique on your App Platform).

=== Cleanup database ===
You can cleanup the instance database inside the instance settings. This starts the vacuumdb process for the instance database which frees disk space of deleted rows.
Note that this process locks the database and that sufficient disk space is needed to complete it!

=== External database host ===
You can optionally configure an external database host, if the database shall be hosted on an external host. 
Note that the App Platform Manager still creates a local database, which is then not used as long as the external host is configured.

What are external databases useful for?:
* User data is too large (files are stored as BLOB in the database)
* Other (non-innovaphone) database servers are to be used due to other regulations
* There is already an external database cluster with its own backup/restore processes which should be used
* More performance is required (please note that a local UNIX socket provides much faster results than a remote database server). Depending on the app and the task of the app, it can still be useful to use a separate server if it is faster.

==== Supported database types ====
In principle, ''PostgreSQL'' and ''MySQL'' are supported. However, please note that the respective app must be designed for the target database server type. If an app has been developed for PostgreSQL, it cannot be operated on a MySQL server.

'''Please note:''' All innovaphone apps are developed exclusively as PostgreSQL apps.

MySQL therefore only makes sense if own apps are developed and MySQL or certain MySQL features are to be used. For such apps, it is very important to deactivate the automatic Application Platform APP-Backup.
The database backup process of the App Platform uses PostgreSQL backup commands, which is why the backup would fail, so the app must be excluded from the backup, and you must take care of the backup yourself.

==== Database creation ====
If you use an external database, you have to create the database itself.
The App Platform Manager itself creates a PostgreSQL database like this (you may respect this on your database host to be compatible with the database implementation inside the Apps):
* CREATE DATABASE "dbname" ENCODING 'UTF8';
* CREATE USER "dbuser";
* ALTER USER "dbuser" WITH PASSWORD 'dbpassword';
* GRANT ALL PRIVILEGES ON DATABASE "dbname" TO "dbuser";
* ALTER DATABASE "dbname" OWNER TO "dbuser";
* REVOKE CONNECT ON DATABASE "dbname" FROM public;

==== Database connection ====
There are different possibilities to specify the host. You can use a DNS-Name, IPv4 or IPv6. A port can be optionally added with a colon.

Our PostgreSQL implementation sets sslmode=prefer, so SSL is used by default if enabled on the server.

==== Backup/Restore ====
External databases are still backuped as normal, but you can't restore such a database with the App Platform Manager on the external host! You must restore such a dump manually on your database host.

==== Database redundancy ====
In principle, it is possible to create redundancies for failure scenarios through this function.

However, there are different scenarios that need to be evaluated on a case-by-case basis:

* One database, multiple App Platforms (primary online / secondary '''offline''') where multiple apps access the same database.
** This mode of operation is legal as long as you can really ensure that only one App Platform is active at a time.

* One database, multiple App Platforms (primary online / secondary '''online''') with multiple apps accessing the same database.
** This operating mode cannot be used for innovaphone apps, as the app itself would have to be developed for such a mode, which it is not.

However, we advise great caution here! The use of the same databases from different nodes may only be used if you can ensure that the databases or runtime environments of apps cannot get into a ''split-brain'' mode.

== Relationship between app instances and app objects in the PBX ==
Typically an app instance is connected to one or more app objects in a customer PBX. This is done by configuring the same parameters on both sides:
* URL
* Password
The password is used by the PBX for authenticating itself, users and services against the app instance.

Some apps need a websocket connection with the PBX. When "websocket" is activated at the app object, the PBX establishes a websocket connection to the app instance and provides the APIs that are configured at the app object.

=== Supported scenarios ===
It is important to understand that the concept does not do any assumptions on how PBXes and APs are correlated. So you can have
* One App Platform for one customer
* One App Platform for many customers
* Many App Platforms for one customer
* Many App Platforms for many customers

Attention: The V13 installer can only configure the scenario "''One App Platform for one customer''". If you want to have a different scenario, you have to configure it manually.

For hosting or cloud scenarios you need special scenarios. Please refer our [[Howto:V13 Hosting| V13 Hosting]] instructions.

=== Restrictions ===
Currently we don't have redundancy for app instances or App Platforms.

== Update of the App Platform itself ==
The App Platform is build on top of buildroot and will receive updates and fixes from time to time. 
You can update the used build inside the Manager App by using the '''Update''' button at the top. 

It is strongly advised to make a full backup (VM) or at least backup all apps (Gateway) before you run such an update!

After the update has been downloaded and verified, your App Platform will reboot.
You can check the installation process after the reboot with the following URL: https://IP-of-AP/manager/ramdisk.log

== App services and multi-threading ==
Each App Service runs in a single process with no multi-threading, independent of the instances of the App Service. However, each instance maintains its own database connection and the database responds to this connect with the creation of a new process. Each app service therefore uses 1+''n'' threads (where ''n'' is the number of instances). All communication between app service instances and their clients must pass the single-threaded web server. On platforms with multi-threading support (i.e. VMware or Hyper-V), up to 1 + ''m'' + ''m'' * ''n'' (with ''m'' being the number of Apps and ''n'' the number of instances per App) threads can be utilized.

= AP Manager settings =

== General ==
* ''Enable Developer mode'': in developer mode, apps can be manually uploaded without an App Store
* ''Disable App security'': each App has an own unix user and if this flag is set, the user can login with SSH for debugging
* ''App Store URL'': the URL to the App Store where Apps are searched and also an update of the AP image itself
* ''Devices app URL'': the URL to the Devices App to manage the AP through Devices
* ''Devices app URL 2'': don't use!
* ''App Platform DNS name'': currently not used
* ''NTP server 1/2'': NTP servers for this AP (in addition to NTP servers retrieved by DHCP)
* ''Timezone string'': A timezone string which is used by the App Platform Manager to do certain jobs according to the configured timezone.
** Note that this doesn't change the timezone of the linux itself!
* ''DNS server 1/2'': DNS servers for this AP (in addition to DNS servers retrieved by DHCP)
* ''Database optimization time'': The database optimization process will be started at this hour (local time), with a random offset of up to 7 hours
* ''Command file'': see [[#Backup_of_the_Apps| Backup of Apps]]

== Security ==
* ''Current Webserver certificates'': shows the current certificates with the ability to download them.
* ''Webserver certificate'': upload a webserver certificate in PEM format
* ''AP Manager password'': the password to the web interface of the AP Manager (normally set through Devices)
* ''Linux root user'': password of the root user (normally set through Devices)
* ''Linux admin user'': password of the admin user (normally set through Devices)

== Let's Encrypt ==

Configure the certificate creation by Let's Encrypt here.

* ''Enable'': turns the automatic creation on or off
* ''Let's Encrypt App URL'': the URL of your Connector for Let's Encrypt App Service. You can copy&paste this URL from your Connector for Let's Encrypt PBX Manager Plugin
* ''Let's Encrypt App Password'': the client password of your Connector for Let's Encrypt App Service. You can copy&paste this password from your Connector for Let's Encrypt PBX Manager Plugin
* ''Key length'': 2048, 3072 or 4096 (keep in mind, that [[{{NAMESPACE}}:Certificate_management#Certificate_Key_Length_and_CPU_Usage|a higher value provides higher security but also lower performance!]])
* ''DNS Name'': the external DNS names of your device (up to 100 possible)

== Alarms and events ==
* ''URL'': URL to the Events app
* ''Username/Password'': HTTP credentials of the Events app
* ''Email address'': an email address which will get emails on full disk alarms/warnings
* ''Threshold'': All Apps will be stopped and an hourly email sent on reaching this threshold. An alarm is generated 10% before reaching this threshold and an email is sent every 24 hours.

== SMTP ==
SMTP server settings for sending emails from within the AP Manager.

== Replication ==
App Platform [[#App Platform replication|replication settings]]

== Registered Access Domains ==

== Update ==
Updates the App Platform to the latest image available on the App Store.

== Restart ==
Restarts the App Platform.

== Shutdown ==
Shuts down the App Platform.

= App Platform replication =

== Requirements ==

* 13r3 or above on both standby servers and the primary server
* at least an App Platform image starting with version 110002 (otherwise postgresql is too old)
* standby and primary servers must have the same system architecture
** arm gateways (IPx11) just with arm gateways (IPx11)
** arm64 gateways (IPx13) just with arm64 gateways (IPx13)
** x86_64 virtual machines just with x86_64 virtual machines
* the disk size on standby servers must be at least equal as the disk size on the primary server

== General ==
The configuration is done within the App Platform Manager next to the settings button under "Replication".

=== Off ===
No replication is done at all.

=== Primary ===
The App Platform acts as primary server for one or multiple standby servers. 
Max 8 standby servers can be configured. 
 
Every standby server must get a unique name on the primary server which is then also configured on the standby server itself. This is due to the fact, that the primary server preserves data for every standby server while it's not reachable. 
A standby server name must be a valid domain name, although this name is currently not used as DNS name (but might be used in the future). 
 
The password is randomly pregenerated and must be used as handed by the App Platform Manager.

==== PostgreSQL port ====
The default PostgreSQL port is 5432 and can't be changed on the primary. It must be reachable through your firewall or at least forwarded on a different port towards this App Platform on port 5432.

=== Standby ===
Configure the password from the primary and one of the not yet used standby server names. 
The host and port must be reachable through the network. You can specify a non default port which then must be forwarded somewhere else to port 5432 on your primary.

*Note: Do '''not''' configure the same standby name on different standby servers, as this will break the replication on at least one standby! 
*Note: On a standby, all '''locally installed apps are removed''' during installation

== Failure detection ==

The replication state on both primary and standby servers are continuously monitored. 
In case of a broken connection, an alarm is triggered at once and just cleared if the failure goes away. 
 
If such an alarm lasts for 5 minutes an email is send. The recipient address must be configured in the App Platform Manager settings under "Alarms and Events" and you must also provide a valid SMTP configuration.

== Failover ==

There is no automatic failover procedure. If you detect the failure state, you must get active yourself.

=== Standby down ===

Fix the standby server and see if the replication comes up again. If not, setup a new standby server which will replicate the whole database cluster from scratch.

=== Primary down ===

If the primary is down and cannot be brought into life again, you must take the following steps, depending on your configuration:

==== One standby server ====

* Disable the replication in the replication configuration. You will then have a standalone App Platform afterwards.

==== Multiple standby servers ====

* Change the replication type on one of the standby servers from standby to primary. Please note that the other standby entries must still exist here (they are automatically offered)!
* Change the host entry on the other standby servers to the new standby server. The standby server will sync the whole database cluster again, which will take time.

==== Configuration changes ====

You must also tell the PBXes and other tools to use the new primary server.

* You may simply change the IP address behind the DNS of your primary server to point to the new primary server.
**Note: to ensure rapid recognition of the new DNS target, the definition of an appropriate TTL value is recommended
* Without DNS, you must currently modify the configuration by replacing the IP address of the old primary with the new address.
** This must be done in every master PBX configuration.
** This must be done in every App configuration which may use this IP address, e.g. Devices which rolls out an alarm server configuration

== App Platfom update ==

If you're running an active standby server and the major version of the PostgreSQL database didn't change, you can simply update primary and standby servers independently. 
 
If it contains a ''new major version'' of the PostgreSQL database, you must follow these steps:

* deactivate replication on all standby servers (which promotes these standby servers to active servers)
* ensure that the '''same''' App Platform Manager version is running on primary and standby servers!
* perform the App Platform update on the primary server
* perform the App Platform update on the standby servers
* reactivate replication on the standby servers (which will do a full replication again, so it might take some time)

Alternativly you may setup the standby server from scratch directly with the new App Platform image version.

Sadly there is currently no better method offered by PostgreSQL to perform such an upgrade.

See also https://wiki.innovaphone.com/index.php?title=Howto14r2:Firmware_Upgrade_V14r1_V14r2#App_Platform_and_Apps

== Technical backgrounds ==

=== Streaming replication ===

We use the asynchronous [https://www.postgresql.org/docs/9.3/warm-standby.html#STREAMING-REPLICATION streaming replication of PostgreSQL]. A transaction thus just waits for a commit on the primary server. Standby servers will receive the transaction asynchronously afterwards to avoid a reduced writing performance. 
A primary server keeps the neccessary WAL files for every standby server until the standby fetched the neccessary information. 
This fact can lead to higher disk space usage on the primary if one or multiple standby servers are offline for a while.

Take care to fix broken replications as soon as possible to avoid a full disk on the primary server!

=== What is replicated ===
The whole database cluster of an app platform is replicated. This includes every database of every instance and the database of the App Platform Manager itself. 

=== App Services on standbys ===
The database of the App Platform Manager itself also contains the App service binaries to be able to restore applications in a failover case. 
You do not have to install App services on the standby if you install them on the primary. 
App Platform Manager and Webserver can be updated as usual through the App Store or the Devices App if the standby is connected to Devices.

=== App Platform Manager configuration of the standby server ===
The App Platform Manager configuration of the standby server cannot be stored inside the database, as the database is readonly. So it is stored inside a configuration JSON file under ''/home/root/standby.conf''. 
This configuration is backed up as usual by a Devices backup job and can be also manually restored on a standby (not on a primary though!).

Configuration options from the primary are not synced to the standby server, as the standby server has its own configuration (as it could be in a different network etc.)!

=== No automatic failover ===

There is currently no automatic failover mechanism. PostgreSQL doesn't offer multi master replication, so writing is just possible on the primary itself. Standby servers have a readonly database. 
Let's consider the following use case if we would implement an automatic failover with the current technical possibilities: 
* The primary server is connected to a master PBX.
* A slave PBX is also connected to the primary server in another location.
* A standby server is in this location and replicates from the primary.
* The internet connection between primary and standby fails.
* The standby promotes itself to primary, so that the master PBX now writes to the old primary and the slave PBX now writes to the "new" primary.
* The internet connection comes up again and both primary and standby servers now have databases which are out of sync and which cannot be merged.

=== Security ===

* port 5432 must be reachable on the App Platform
* For every standby a PostgreSQL user is created with the REPLICATION role on the primary. Just this user has access to the database server from non localhost connections.
* You cannot establish a standard connection with such a user and modify/read from tables.
* The replication connection is established over TLS by default.

= App Installer PBX Manager Plugin =
== Requirements ==

* V14 and above

== General ==

The app installer plugin allows IT administrator (with access to the PBX Manager) to install/update/delete new apps from the innovaphone app store including Partners apps. It is automatically available with existing app platforms or after adding a new one in the PBX Manager.
It offers a view to the App Platform Manager‘s App Store with all the available functionalities and simplifies the install, update and uninstall of apps.

== Dedicated AP for each user ==

Installing a new app will install the app service and add a new instance with the user’s domain. The instance is automatically started. 
This further enables the configuration of the instance through its respective PBX Manager plugin. 
Uninstalling the app will remove the app service and the corresponding instance.

== Shared AP between users ==

Installing a new app works in a similar way to that of the dedicated AP. However, each time a new user installs the app, only a new instance is created if the app service is already installed. 
A user can uninstall the app, in this case the corresponding instance is deleted. If no more instances exist, then the app service is uninstalled. 
The administrator can only update the app service in such scenario.

= Known Issues =

== Reboot after an image update hangs (ARM gateway) ==

If it happens, that the App Platform doesn't recover after the reboot, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
If '''Kernel command line''' is set to '''/dev/ram0''', the App Platform booted the ramdisk. 
 
Try to fetch the upgrade log file:
https://[APP-PLATFROM-IP/DNS]/manager/ramdisk.log
 
If this doesn't work, try to login with putty in this case (default credentials admin/ipapps and root/iplinux) and issue this command: 
''cat /apps/install_step1.log'' 
 
If this file contains '''finished''' at the end, you can reconfigure the settings under App Platform -> General: 
* press '''Stop'''
* Initrd file: empty
* Kernel command line: '''root=/dev/sda3'''
* Ramdisk size: empty
* press '''Start'''

The App Platform should boot and run the already updated image.

<pre style="color: red; font-size:150%;">---WARNING---
If the file doesn't contain "finished" at the end, you may still need to wait, as an upgrade may take some time!
Do not reconfigure without being sure that the upgrade has finished, otherwise your system may won't run!</pre>

== Reboot after an image update boots always into rescue mode (virtual machine) ==

This most likely means that the image installation didn't finish the first time and was interrupted before the bootloader settings could be changed back to the default partition. 
 
If your App Platform doesn't boot or isn't normally accessible after manual selection of the standard entry in the boot menu, you need to '''revert''' to a '''snapshot/backup''' prior to the update. 
If your App Platform runs normally though, you can follow this instruction to change the default boot entry: 
 
* boot into the '''rescue''' partition
* login with root/iplinux
* edit the file /boot/grub/grub.cfg
** search the line with '''set default=0''' and change it to '''set default=1'''
** reboot

== App Platform doesn't start after an update ==

=== Gateway ===
If it happens, that the App Platform doesn't want to start an update, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
* '''Shutdown''' the App Platform and '''Stop''' it 
* Set '''Kernel command line''' to '''/dev/ram0''' 
* Set '''Initrd file''' to '''ramdisk.ext2.xz''' 
* Set '''Ramdisk size''' to '''100000''' 
* '''Start''' the App Platform now. 

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

Note: This process can take a while, after it's finished it reboots and automatically change the '''Kernel command line''' value.

=== Virtual Machine ===

Boot into the '''rescue''' partition.

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

=== It still doesn't start ===

If it still doesn't start, configure the App Platform to boot from /dev/sda3 (or inside a VM start the second boot loader entry) and login with SSH as root.
Then do a first check to verify that you have a specific error due to an incomplete update or a [[Howto15r1:Firmware Upgrade V14r2 V15r1#AP Upgrade to Image 130006|wrong update order]]:

* /etc/init.d/S92manager stop
* /apps/manager/manager
* if this outputs '''error while loading shared libraries: libcrypto.so.3:''' you have a manager version which cannot run on the current image.

In this case you must download an older build (14r1 1410593):

* /etc/init.d/S92manager stop
* wget --no-check-certificate -O /apps/manager/manager https://webbuild.innovaphone.com/1410593/arm/manager/manager
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* wget --no-check-certificate -O /apps/webserver/webserver https://webbuild.innovaphone.com/1410593/arm/webserver/webserver
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* chown root:root /apps/manager/manager
* chown root:root /apps/webserver/webserver
* chmod +x /apps/manager/manager
* chmod +x /apps/webserver/webserver
* echo 110000 > /mnt/sda1/label
** this allows the manager to perform an image update again
* /etc/init.d/S92manager start
* now perform an image update and '''afterwards''' update your apps again

== Webserver doesn't respond after an image update ==

If you can't reach the web UI after an image update, please try to connect with SSH as admin user and delete old coredumps, which may prevent the App Platform Manager from starting correctly:
* su root (become root)
* rm -f /mnt/sda2/log/core_dumps/*/*
* /etc/init.d/S92manager restart

Check if you can now reach the App Platform again.

= Tracing =
Each App Service has its own log file, which can be accessed through the Manager App. You can configure a log file size for each App Service. 
Each App Intance has its own trace flags. The following trace flags can be set: 

* Alarm client: used by the manager to send alarms to an alarm server
* App: logs from the App Service itself
* App WebSocket: logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
* AppSharing: just native clients
* AppProxy: just native clients, logs requests which are proxied between the local webserver and the remote server
* Audio: just native clients
* Browser: just native clients
* Command: the command interface is used to execute shell commands, e.g. used by the manager App
* Config: logs config changes of an App
* Database: database logs
* DB files: database file logs
* DNS: DNS request logging
* DTLS: just native clients, DTLS request logging
* Ethernet: interface to get ethernet adapater infos, just manager App
* File: logs for file system access (synchronous), e.g. manager App
* Files: logs for file system access (asynchronous)
* HTTP client: http client logs
* HTTP file: logs for static HTTP files
* ICE: just native clients
* LDS: local domain sockets
* Media: just native clients
* Media channel: just native clients
* Process: IProcess interface logs which is used for spawning, killing processes etc.
* SMTP: SMTP client logs
* TCP: TCP logs
* Time: ITime interface logs
* TLS: TLS logs
* TURN: just native clients
* UDP: UDP logs
* Video: just native clients
* WebSocket client: logs outgoing websocket connections
* Webserver traffic: logs incoming HTTP traffic, which is forwarded from the webserver to the App
* WebDAV service: logs WebDAV requests to the App
* Webserver: enables webserver specific logs

== RPCAP ==

If you open the Manager App, click on the Manager in the left list and then on the Diagnostics button, you can enable RPCAP. 
You can add the interface in wireshark with the string:
rpcap://<APP-Platform-IP>/eth0

'''Please don't forget to disable RPCAP after your testing!'''

= How-Tos =

== How to retrieve files from the App Platform ==
To retrieve files from the App Platform which can not be retrieved via the App Platform manager UI, you can connect to the App Platform using the SCP protocol on port 22. 
 
First copy files to /home/admin as root with Putty or another SSH client:
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''su root'' to be root (''iplinux'' as default password)
 
You can now copy files to ''/home/admin'' (e.g. from /var/log/apps/manager/...). 
 
You can create a tar archive with all logs like this:
* cd /home/admin
* tar -cf - /var/log/* | xz -z - > log.tar.xz
** you may want to exclude coredumps (due to their size):
** tar -cf - --exclude=/var/log/core_dumps/* /var/log/* | xz -z - > log.tar.xz
* chown admin:admin /home/admin/log.tar.xz
 
Then copy the files to your local system, e.g. with WinSCP 
* use ''SCP'' as protocol (NB: WebDAV is not supported on most of the directories on the App Platform )
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''/home/admin'' as start directory
* copy the needed files

== App Platform disk space warning ==

If the configured threshold is reached, all Apps are stopped inside the App Platform . You must then free disk space somehow.

=== Find large instances ===
Click through your apps in the tree on the left side and take a look at the database size of each instance.

=== Delete data inside an instance ===
It depends on the type of app if you can delete data or not. E.g. you can start the Files app and delete files inside this app. 
This won't reclaim disk space though due to the way how PostgreSQL databases work, so you need to follow this guide to reclaim the disk space:

* start the corresponding App
* delete data inside the App
* optimize disk usage of the database by cliking on the button "Clean up database" under Edit instance. If this does not help, continue with the following steps.
* stop the corresponding App again
* download a backup of the instance (backup button at the top), this backup contains the whole instance data, also the password of the instance
* delete this specific instance
* restore the downloaded backup (restore button at the top)

Depending on the hardware and the size of the instance, this process may take hours to complete!

=== Resize the disk ===
The resizing of a disk is just possible for virtual machines, see [[#Resizing the disk of a Virtual machine|Resizing the disk of a Virtual machine]].

=== Delete the whole instance ===
If there is no other possibility, you can delete the whole instance. Afterwards you recreate the instance with the same values and a new random password. Don't forget to set this password in the corresponding PBX App objects though!

=== Restart the Apps or the App Platform ===
If you have enough disk space again, you must either restart the whole App Platform or you manually start all Apps again.

== App Platform/Apps app not online anymore due to full disk ==
If the apps app is not online anymore and you can't access any apps anymore, try to login with an SSH client to see if your disk is full.
Login as admin and afterwards as root (su root). 
 
* issue '''df -h''' and see the disk usage of /dev/sda2, if this is 100%, your disk is too full
* stop the manager
** /etc/init.d/S92manager stop
* empty the 500 MB file, which is exactly for this case here (manager must be 13r1 SR9 or higher to have this file)
** echo "" > /mnt/sda2/empty_if_no_space
* delete log files to recover some space
** rm /var/log/apps/*/*
** rm /var/log/core_dumps/*/*
* restart the postgresql server (see the output if this worked or not)
** /etc/init.d/S50postgresql restart
* restart the manager
** /etc/init.d/S92manager restart
* wait until everything is online again
* open the Apps app and try to find the instance which uses the most disk space and try to delete files/content from it
** you may want to stop all app services first to prevent more writes to the database
** if not possible, you can delete this instance, but you'll loose all data from this instance then!
* after that you can try [[{{NAMESPACE}}:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files|Reference14r2:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files]] to free up space
** If this does not work you can create a backup from the database, delete the database and import the database again.
* free up at least 500 MB so that the manager can create the file again
* delete /mnt/sda2/empty_if_no_space if you are done and restart the manager:
** rm /mnt/sda2/empty_if_no_space
** /etc/init.d/S92manager restart
** the manager restart automatically recreates the empty_if_no_space file if this file doesn't exist

Make sure, that you do '''not''' have backups configured to a local files instance while this files instance is not excluded from backups.
An instance can be excluded from backups in the instance settings in the App Platform Manager.

If all of this doesn't help, you can resize the file system on a VM:
* proceed with [[{{NAMESPACE}}:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine|Reference14r2:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine]]

== Resizing the disk of a Virtual machine ==

Do '''NOT''' resize if you're running an App Platform version higher than '''110000''' and lower than '''110027''' or '''130007''' and lower than '''130015''' or your data will be lost!
Please update your App Platform to version 130015 or higher before you start resizing your disk.

* stop the VM
* expand the disk using your VM utilities
* start the VM and boot from the first boot entry '''rescue/setup'''
* login with '''root''' and '''iplinux'''
* execute this command: '''/home/root/install_step1.sh log.txt resize'''
* the VM reboots automatically after a successful resize

== Shrink the physically size of PostgreSQL database files ==
Tuples that are deleted in your database are not physically removed from the database-file. So the claimed space on the harddisk is still in use after the delete operation.
If you need to free up some disk space you can force to reorganize the physically database-file on your harddisk.

You can also start this process through the instance settings as long as the App Platform Manager is still running.

'''Important: You are operating on the Database, you have to make a Backup of your Database before you do this!'''

Login via SSH to the APPlatform with the ''admin'' User
su root

=== All databases ===
/etc/init.d/S92manager stop # not always needed, but in case of database errors recommended, of course no app is online then
sudo -u postgres reindexdb -a
sudo -u postgres vacuumdb -a -f
/etc/init.d/S92manager restart # just execute if the manager has been stopped above

=== single database ===
sudo -u postgres reindexdb -d dbname # for a single database with dbname
sudo -u postgres vacuumdb -d dbname -f # for a single database with dbname

Note: This may take some time and the App database is not available during this time

After the process you can check the free dispace via <code>df -h</code>. You can check the claimed space from the database file with the command <code>du -sh /mnt/sda2/pgsql/</code>.

== Change IP Addresses / DNS Names / System Name ==

If you want to change the System Name or the DNS Name of the PBX and/or App Platform Platform you must change records manually '''in the described order'''!
You have to know the Admin password to directly Login to the App Platform .

=== App Platform ===
; Settings - General
* ''Devices app URL''
* ''App platform DNS name''

; Settings - Alarms and Events
* ''URL''

; All Instances
* ''Domain''
* ''Webserver path''

=== PBX ===
Download the configuration and ''search/replace'' in the config file. Upload the config file and reboot.

Manual:
* ''URL'' in all PBX Object (Apps, Voicemail ...)
* [[{{NAMESPACE}}:Gateway/CDR|CDRx]]
* [[{{NAMESPACE}}:PBX/Config/General|IP address for App Platform]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reset Password Page]]
* [[{{NAMESPACE}}:PBX/Config/Authentication|Verification link]]

Depending on your change you have to activate/deactivate the Setting [[{{NAMESPACE}}:PBX/Config/General|Operation without DNS]]

=== Additional Devices / Steps ===
* ''Devices Registration URL''
** There is no automatism to change the URL on all devices in your setup.
** If you have the option to use DHCP, you can temporarily overwrite the [[{{NAMESPACE}}:Services/Update|Update URL]] and execute a [[{{NAMESPACE}}:Concept_Update_Server|custom update script]] to change the ''Device Registration URL''
* ''Alarm server''
* Reverse Proxy configuration
* Change ''Domain Name'' in Devices if you have also changed the system name

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

initial error at 1500329378: ext4_journal_start_sb:328
last error at 1500329378: ext4_journal_start_sb:328

Or you get events like "Broken file system" from your App Platform .

This indicates a file system failure on the Linux Installation.

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

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

=== Gateway ===

* Open the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the Kernel command line from root=/dev/sda3 to root=/dev/ram0
** modify the Initrd file to ramdisk.ext2.xz
** modify the ramdisk size to 100000
** start Linux again
:: This will run Linux on another (hopefully sane) partition.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system

* go back to the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/ram0'' to <code>root=/dev/sda3</code>
** clear the Initrd file field
** clear the ramdisk size field
** start Linux again
:: This will run Linux on the original partition.

=== VM ===

Restart the VM and select the first entry in the boot menu from grub.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system
* Reboot your VM
[[Category:Concept]]

== How to create a memory dump of a running process ==

Sometimes it's usefull to have a memory dump of a running process to investigate certain issues.

* login with SSH and become root
* find out the PID of the relevant process, e.g. with ''ps aux | grep /apps/manager/manager | grep -v grep''
* gdb --pid PID -ex gcore --batch
* this creates a core file core.PID
* download this core file with WinSCP or similar tools

== Move instance database to external database host ==

In case you want to use an external database server instead of the integrated:

* download a backup of the specific instance over the App Platform Manager
* create a postgresql database on the external host:
** createdb --encoding=UTF-8 exampledb
* restore the backup
** pg_restore -d exampledb backup-exampledb.dump
* change the ownership to a specific postgresql user (which you have to create yourself first)
** psql -d postgres -c "ALTER DATABASE exampledb OWNER TO exampleuser"
* configure the database host, name, user and password on the instance inside the App Platform Manager

Reference14r1:Concept App Platform

2025-08-14T07:08:12Z

Dde: /* Resizing the disk of a Virtual machine */

= General =
* V13 uses [https://buildroot.org/ buildroot]
* this is an own (innovaphone) collection of packages
* For further information see: [https://buildroot.org/docs.html Buildroot Documentations]

== Requirements ==

* V13 or above
* Gateway (arm): IPx10 (with CF card) or IPx11 (with mSATA SSD)
* Gateway (arm64): IPx13 (with m2 SSD)
* Virtual (x86_64)
** HyperV with [https://docs.microsoft.com/de-de/windows-server/virtualization/hyper-v/deploy/upgrade-virtual-machine-version-in-hyper-v-on-windows-or-windows-server#supported-virtual-machine-configuration-versions VM-configuration Version] 6.2 (minimum: Windows 10 or Windows Server 2016)
** VMWare
** Proxmox/KVM/Qemu

== Default credentials ==

'''During INSTALL, the default passwords are replaced with the global Admin PW!'''
* SSH-Login with '''admin''' and '''ipapps'''
* root login with '''root''' and '''iplinux''' (the root login is not directly possible, you have to login as admin first and use the command ''su root'')
* manager App (web login) '''pwd'''

= App Platform - arm/arm64 (Gateway)=

* The installation image has a size of ~50MB. During installation, the following partitions are created<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 fat32: 200MB (contains ramdisk, rootfs and kernel)
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB

When comparing potential performance of the IPxx11 platform compared to the IPxx10 platform, there are some major differences:
* SSDs found in the xx11 are faster and more reliable than the CF found in the xx10
* the available RAM for the App Platform (as specified in column ''RAM for LAP (GB) out of RAM'' in chapter ''Technical data and recommended number of users supported'' of [[Howto:How_to_implement_large_PBXs#Technical_data_and_recommended_number_of_users_supported|How to implement large PBXs]]) is factor 6 larger on the xx11 (1,536 GB) than on the xx10 (0,256 GB))
* the xx11 has gigabit Ethernet while the xx10 has 100Mbps Ethernet. The xx10 is therefore not well suited for Apps with larger network traffic, such as Recordings
* the CPU of the xx11 (although it runs on the same frequency) is roughly 20% faster than the xx10

While it is hard to predict the performance of the App Platform in a specific scenario, we see that in a real life environment an App Platform running on an xx11 platform can well support 150 users. The xx10 platform is estimated to support 120 users. Because CPU performance is the limiting factor, larger setups can be built based on the virtual machine platform (see [[#App_services_and_multi-threading|App services and multi-threading]] below).

<references/>

= App Platform - x86-64 (Virtual Machine 64bit) =

* The default disk size is 16GB. It should be increased '''before''' the first start if needed!
* Multiple CPUs are supported, default is one CPU
* default RAM: 512MB
* static IP address, DNS, Gateway can be configured with the command '''setip''' on the console. Run '''setip --help''' to get a list of parameters. (Example: setip --addr=x.x.x.x --mask=x.x.x.x --gateway=x.x.x.x --dns1=x.x.x.x)
* If you have permission problems change to su user (Password is iplinux or your new admin password)
* To figure out your ip address you can use the command: ''ip address'' on the console.
* '''loadkeys de''' can be used to change to german keyboard layout (etc.)
* partitions<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 ext2: 350MB (contains ramdisk, rootfs and kernel)
*** the real partition format size is smaller but there is no need to monitor sda1 as sda1 won't grow during usage of the App Platform
*** sda1 is completely exchanged during an image update and its size might have changed but will never exceed these 350MB
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB
* VMWare Tools: Open VM Tools
* Qemu Guest Agent: installed since 110032
** The qemu guest agent can be configured in Proxmox with ''Virtio'' or ''ISA''. You '''must''' use '''ISA''', as Virtio is currently not supported.

<references/>

= Installation =
==ARM Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-armel.img'' image file.
* The installation runs without any further required step.

==ARM64 Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-arm64.img'' image file.
* The installation runs without any further required step.

==Virtual machine==

* Import the image into your server environment.
** Proxmox: follow this description here, just with the app-platform-ova.zip: https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Proxmox_VE
* Edit the disk size, if needed.
* Start the machine and wait until it reboots and starts again.
* Note: If you need to access an IP addresses available through a VPN connection from from inside the virtual machine, it could be that you need to set the network of your VM to NAT (and also add the URL for an IP to /etc/hosts)

[https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Configuration More Configuration Hints regarding VM Ware]

== Backup of the Apps ==

Each App Service can have multiple instances and each instance has its own database. The manager app itself also has its own database. 
There are no other files which need to be backuped. 
The standard way to backup the databases is through the Devices App [[{{NAMESPACE}}:Concept_App_Service_Devices#Backups]]. 
 
An alternate way is to use a command file which is similar to the command files from the firmware.

===Commands===
* '''times''' 0,12 # backup only at 0 or 12 o'clock
* '''backup-instances''' http://user:pw@ip/path/#I-#D.dump PUT
** PUT and POST are supported, all instances including the manager itself are saved
* '''backup-instance''' http://user:pw@ip/path/#I-#D.dump apidemo example.com PUT
** backup a single instance with instance name and instance domain
* '''backup-manager''' http://user:pw@ip/path/#I-#D.dump

===Hash parameters===
* #L App Platform label (neu), e.g. 10024
* #A App label (neu), e.g. 130004
* #I instance name (neu), e.g. reporting1
* #D instance domain (neu), e.g. innovaphone.com
* #m MAC address of the LAP, e.g. 00ab11eeff
* #d Current date and time (plain UTC without daylight saving and timezone adjustments) 20051010-170130
* #bn rolling backup index (n >=0 and <= 9, just one digit)
* ## escapes a hash mark

= App Platform Infrastructure and Concept =
== Webserver ==
The app platform includes a webserver that is highly optimized for handling many Websocket connections at a low memory footprint.
All apps use that webserver by registering for specific HTTP subpath. So they can all use the same HTTP/HTTPS ports - typically the standard ports.

=== Import Custom SSL Certificate ===
You have to upload a PEM Certificate with the following chain structure and without password encoding.

-----BEGIN CERTIFICATE-----
(certificate: eg. your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: eg. DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: eg. TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: eg. your_domain_name.key)
-----END RSA PRIVATE KEY-----

If you have problems generating the complete and correct certificate chain, you can use tools such as https://whatsmychaincert.com/ as an aid.
'''Please keep in mind that you never give away the private part of your key.'''

=== Known issues ===
*The app platform webserver can use only the default http/https ports 80/443.
*By design, there is no possibility to restore the default webserver certificate on the App Platform, if another certificate was once uploaded. 
**If nevertheless needed, you must login with Putty (see [[#How_to_retrieve_files_from_the_AP | Retrieve files]]) and execute these commands as root:
**''psql -d manager -c "DELETE FROM config WHERE name='webserverCertificate'"''
**''/etc/init.d/S92manager restart''
*The app platform webserver interprets URLs case-sensitive. In other words, <nowiki>http://<addr>/file.txt</nowiki> is not the same as <nowiki>http://<addr>/FILE.TXT</nowiki>

== Database ==
The app platform creates a database for each app instance with a given password. In the installer there will be used randomly generated passwords. You can set a new database password for every instance in the Application Platform.

The apps should store all data in that database. That makes sure that a consistent backup and restore of app instances can be done by the app platform manager.
In hosted scenarios, having separate databases for each instance also makes sure that the data of different customers are clearly separated and can easily be moved from one physical platform to another.

The default configuration decline database request from extern. If you need external access you can change the PGSQL configuration (as root) in the file ''/mnt/sda2/pgsql/pg_hba.conf''.
After editing pg_hba.conf, the database-service has to be restarted with the command <code>/etc/init.d/S50postgresql restart</code>
(Please think about it before you do it, because a better way is to create your own local app with local database access.)

You can find the official documentation for the pg_hba.conf here: https://www.postgresql.org/docs/14/auth-pg-hba-conf.html

Please note that you do this on your own responsibility, that it makes sense to create a backup of the original pg_hba.conf
and that you may break your database server if you do not know exactly what you do!

Sometimes the Apps are not proper working after this. You can wait a while until everything is working again or you go the hard way:
* stop the manager
** <code>/etc/init.d/S92manager stop</code>
* restart the database-service (maybe not really necessary, but makes a good feeling)
**<code>/etc/init.d/S50postgresql restart</code>
* start the manager
** <code>/etc/init.d/S92manager start</code>

== App Platform Manager ==
The App Platform Manager is the central component of the App Platform. It does the following:
* Installing app services by downloading the binaries from an app store.
* Running and monitoring app services. If an app service crashes it is restarted, automatically.
* Management of app instances and providing them with the environment they need:
** A database
** A webserver path
** A password for authentication
* Backup and restore of app instances.
* Collecting debug information like tracing and crash dumps.
* System monitoring (CPU usage, memory usage, etc).

== App Services ==
App services are runned by the App Platform Manager. They implement an interface that is used by the manager to start, stop and configure app instances. Each service runs in a separate child process of the manager.

== App Instances ==
The actual functionality of an app service is provided by app instances. They run in the same process as the app service but have a distinct webserver path and their own database. There can be 0..n instances of an app service. Instances can optionally host (web) apps that can be opened in the myApps client.

Each instance of an App service has two passwords. The instance password itself and a database password. If you want to change it you must update the password on both sides. 
The instance password must match to the password in the corresponding PBX App objects, while one instance can have different App objects. 
The database password must be just known to the manager and not outside of the App Platform.

The ''Database name'' and ''Database user'' are both limited to a length of 63 characters. By default, the App Manager would create ''<domain>''_''<instance-name>'' as value for both. This is why it is recommended to use instance names so that length(name) + length(domain) is less than 63 characters. However, if this is not possible, you can manually shorten the suggested values (both must still be unique on your App Platform).

=== Cleanup database ===
You can cleanup the instance database inside the instance settings. This starts the vacuumdb process for the instance database which frees disk space of deleted rows.
Note that this process locks the database and that sufficient disk space is needed to complete it!

=== External database host ===
You can optionally configure an external database host, if the database shall be hosted on an external host. 
Note that the App Platform Manager still creates a local database, which is then not used as long as the external host is configured.

What are external databases useful for?:
* User data is too large (files are stored as BLOB in the database)
* Other (non-innovaphone) database servers are to be used due to other regulations
* There is already an external database cluster with its own backup/restore processes which should be used
* More performance is required (please note that a local UNIX socket provides much faster results than a remote database server). Depending on the app and the task of the app, it can still be useful to use a separate server if it is faster.

==== Supported database types ====
In principle, ''PostgreSQL'' and ''MySQL'' are supported. However, please note that the respective app must be designed for the target database server type. If an app has been developed for PostgreSQL, it cannot be operated on a MySQL server.

'''Please note:''' All innovaphone apps are developed exclusively as PostgreSQL apps.

MySQL therefore only makes sense if own apps are developed and MySQL or certain MySQL features are to be used. For such apps, it is very important to deactivate the automatic Application Platform APP-Backup.
The database backup process of the App Platform uses PostgreSQL backup commands, which is why the backup would fail, so the app must be excluded from the backup, and you must take care of the backup yourself.

==== Database creation ====
If you use an external database, you have to create the database itself.
The App Platform Manager itself creates a PostgreSQL database like this (you may respect this on your database host to be compatible with the database implementation inside the Apps):
* CREATE DATABASE "dbname" ENCODING 'UTF8';
* CREATE USER "dbuser";
* ALTER USER "dbuser" WITH PASSWORD 'dbpassword';
* GRANT ALL PRIVILEGES ON DATABASE "dbname" TO "dbuser";
* ALTER DATABASE "dbname" OWNER TO "dbuser";
* REVOKE CONNECT ON DATABASE "dbname" FROM public;

==== Database connection ====
There are different possibilities to specify the host. You can use a DNS-Name, IPv4 or IPv6. A port can be optionally added with a colon.

Our PostgreSQL implementation sets sslmode=prefer, so SSL is used by default if enabled on the server.

==== Backup/Restore ====
External databases are still backuped as normal, but you can't restore such a database with the App Platform Manager on the external host! You must restore such a dump manually on your database host.

==== Database redundancy ====
In principle, it is possible to create redundancies for failure scenarios through this function.

However, there are different scenarios that need to be evaluated on a case-by-case basis:

* One database, multiple App Platforms (primary online / secondary '''offline''') where multiple apps access the same database.
** This mode of operation is legal as long as you can really ensure that only one App Platform is active at a time.

* One database, multiple App Platforms (primary online / secondary '''online''') with multiple apps accessing the same database.
** This operating mode cannot be used for innovaphone apps, as the app itself would have to be developed for such a mode, which it is not.

However, we advise great caution here! The use of the same databases from different nodes may only be used if you can ensure that the databases or runtime environments of apps cannot get into a ''split-brain'' mode.

== Relationship between app instances and app objects in the PBX ==
Typically an app instance is connected to one or more app objects in a customer PBX. This is done by configuring the same parameters on both sides:
* URL
* Password
The password is used by the PBX for authenticating itself, users and services against the app instance.

Some apps need a websocket connection with the PBX. When "websocket" is activated at the app object, the PBX establishes a websocket connection to the app instance and provides the APIs that are configured at the app object.

=== Supported scenarios ===
It is important to understand that the concept does not do any assumptions on how PBXes and APs are correlated. So you can have
* One App Platform for one customer
* One App Platform for many customers
* Many App Platforms for one customer
* Many App Platforms for many customers

Attention: The V13 installer can only configure the scenario "''One App Platform for one customer''". If you want to have a different scenario, you have to configure it manually.

For hosting or cloud scenarios you need special scenarios. Please refer our [[Howto:V13_Hosting| V13 Hosting]] instructions.

=== Restrictions ===
Currently we don't have redundancy for app instances or App Platforms.

== Update of the App Platform itself ==
The App Platform is build on top of buildroot and will receive updates and fixes from time to time. 
You can update the used build inside the Manager App by using the '''Update''' button at the top. 

It is strongly advised to make a full backup (VM) or at least backup all apps (Gateway) before you run such an update!

== App services and multi-threading ==
Each App Service runs in a single process with no multi-threading, independent of the instances of the App Service. However, each instance maintains its own database connection and the database responds to this connect with the creation of a new process. Each app service therefore uses 1+''n'' threads (where ''n'' is the number of instances). All communication between app service instances and their clients must pass the single-threaded web server. On platforms with multi-threading support (i.e. VMware or Hyper-V), up to 1 + ''m'' + ''m'' * ''n'' (with ''m'' being the number of Apps and ''n'' the number of instances per App) threads can be utilized.

= AP Manager settings =

== General ==
* ''Enable Developer mode'': in developer mode, apps can be manually uploaded without an App Store
* ''Disable App security'': each App has an own unix user and if this flag is set, the user can login with SSH for debugging
* ''App Store URL'': the URL to the App Store where Apps are searched and also an update of the AP image itself
* ''Devices app URL'': the URL to the Devices App to manage the AP through Devices
* ''Devices app URL 2'': don't use!
* ''App Platform DNS name'': currently not used
* ''NTP server 1/2'': NTP servers for this AP (in addition to NTP servers retrieved by DHCP)
* ''Timezone string'':
* ''DNS server 1/2'': DNS servers for this AP (in addition to DNS servers retrieved by DHCP)
* ''Database optimization time'': The database optimization process will be started at this hour (local time), with a random offset of up to 7 hours
* ''Command file'': obsolete, use the Devices App for backups!

== Security ==
* ''Current Webserver certificates'': shows the current certificates with the ability to download them.
* ''Webserver certificate'': upload a webserver certificate in PEM format
* ''AP Manager password'': the password to the web interface of the AP Manager (normally set through Devices)
* ''Linux root user'': password of the root user (normally set through Devices)
* ''Linux admin user'': password of the admin user (normally set through Devices)

== Let's Encrypt ==

Configure the certificate creation by Let's Encrypt here.

* ''Enable'': turns the automatic creation on or off
* ''Let's Encrypt App URL'': the URL of your Connector for Let's Encrypt App Service. You can copy&paste this URL from your Connector for Let's Encrypt PBX Manager Plugin
* ''Let's Encrypt App Password'': the client password of your Connector for Let's Encrypt App Service. You can copy&paste this password from your Connector for Let's Encrypt PBX Manager Plugin
* ''Key length'': 2048, 3072 or 4096 (keep in mind, that [[{{NAMESPACE}}:Certificate_management#Certificate_Key_Length_and_CPU_Usage|a higher value provides higher security but also lower performance!]])
* ''DNS Name'': the external DNS names of your device (up to 100 possible)

== Alarms and events ==
* ''URL'': URL to the Events app
* ''Username/Password'': HTTP credentials of the Events app
* ''Email address'': an email address which will get emails on full disk alarms/warnings
* ''Threshold'': All Apps will be stopped and an hourly email sent on reaching this threshold. An alarm is generated 10% before reaching this threshold and an email is sent every 24 hours.

== SMTP ==
SMTP server settings for sending emails from within the AP Manager.

== Replication ==
App Platform [[#App_Platform_replication|replication settings]]

== Registered Access Domains ==

== Update ==
Updates the App Platform to the latest image available on the App Store.

== Restart ==
Restarts the App Platform.

== Shutdown ==
Shuts down the App Platform.

= App Platform replication =

== Requirements ==

* 13r3 or above on both standby servers and the primary server
* at least an App Platform image starting with version 110002 (otherwise postgresql is too old)
* standby and primary servers must have the same system architecture
** arm gateways (IPx11) just with arm gateways (IPx11)
** arm64 gateways (IPx13) just with arm64 gateways (IPx13)
** x86_64 virtual machines just with x86_64 virtual machines
* the disk size on standby servers must be at least equal as the disk size on the primary server

== General ==
The configuration is done within the App Platform Manager next to the settings button under "Replication".

=== Off ===
No replication is done at all.

=== Primary ===
The App Platform acts as primary server for one or multiple standby servers. 
Max 8 standby servers can be configured. 
 
Every standby server must get a unique name on the primary server which is then also configured on the standby server itself. This is due to the fact, that the primary server preserves data for every standby server while it's not reachable. 
A standby server name must be a valid domain name, although this name is currently not used as DNS name (but might be used in the future). 
 
The password is randomly pregenerated and must be used as handed by the App Platform Manager.

==== PostgreSQL port ====
The default PostgreSQL port is 5432 and can't be changed on the primary. It must be reachable through your firewall or at least forwarded on a different port towards this App Platform on port 5432.

=== Standby ===
Configure the password from the primary and one of the not yet used standby server names. 
The host and port must be reachable through the network. You can specify a non default port which then must be forwarded somewhere else to port 5432 on your primary.

*Note: Do '''not''' configure the same standby name on different standby servers, as this will break the replication on at least one standby! 
*Note: On a standby, all '''locally installed apps are removed''' during installation

== Failure detection ==

The replication state on both primary and standby servers are continuously monitored. 
In case of a broken connection, an alarm is triggered at once and just cleared if the failure goes away. 
 
If such an alarm lasts for 5 minutes an email is send. The recipient address must be configured in the App Platform Manager settings under "Alarms and Events" and you must also provide a valid SMTP configuration.

== Failover ==

There is no automatic failover procedure. If you detect the failure state, you must get active yourself.

=== Standby down ===

Fix the standby server and see if the replication comes up again. If not, setup a new standby server which will replicate the whole database cluster from scratch.

=== Primary down ===

If the primary is down and cannot be brought into life again, you must take the following steps, depending on your configuration:

==== One standby server ====

* Disable the replication in the replication configuration. You will then have a standalone App Platform afterwards.

==== Multiple standby servers ====

* Change the replication type on one of the standby servers from standby to primary. Please note that the other standby entries must still exist here (they are automatically offered)!
* Change the host entry on the other standby servers to the new standby server. The standby server will sync the whole database cluster again, which will take time.

==== Configuration changes ====

You must also tell the PBXes and other tools to use the new primary server.

* You may simply change the IP address behind the DNS of your primary server to point to the new primary server.
* Without DNS, you must currently modify the configuration by replacing the IP address of the old primary with the new address.
** This must be done in every master PBX configuration.
** This must be done in every App configuration which may use this IP address, e.g. Devices which rolls out an alarm server configuration

== App Platfom update ==

If you're running an active standby server and the major version of the PostgreSQL database didn't change, you can simply update primary and standby servers independently. 
 
If it contains a ''new major version'' of the PostgreSQL database, you must follow these steps:

* deactivate replication on all standby servers (which promotes these standby servers to active servers)
* ensure that the '''same''' App Platform Manager version is running on primary and standby servers!
* perform the App Platform update on the primary server
* perform the App Platform update on the standby servers
* reactivate replication on the standby servers (which will do a full replication again, so it might take some time)

Alternativly you may setup the standby server from scratch directly with the new App Platform image version.

Sadly there is currently no better method offered by PostgreSQL to perform such an upgrade.

== Technical backgrounds ==

=== Streaming replication ===

We use the asynchronous [https://www.postgresql.org/docs/9.3/warm-standby.html#STREAMING-REPLICATION streaming replication of PostgreSQL]. A transaction thus just waits for a commit on the primary server. Standby servers will receive the transaction asynchronously afterwards to avoid a reduced writing performance. 
A primary server keeps the neccessary WAL files for every standby server until the standby fetched the neccessary information. 
This fact can lead to higher disk space usage on the primary if one or multiple standby servers are offline for a while.

Take care to fix broken replications as soon as possible to avoid a full disk on the primary server!

=== What is replicated ===
The whole database cluster of an app platform is replicated. This includes every database of every instance and the database of the App Platform Manager itself. 

=== App Services on standbys ===
The database of the App Platform Manager itself also contains the App service binaries to be able to restore applications in a failover case. 
You do not have to install App services on the standby if you install them on the primary. 
App Platform Manager and Webserver can be updated as usual through the App Store or the Devices App if the standby is connected to Devices.

=== App Platform Manager configuration of the standby server ===
The App Platform Manager configuration of the standby server cannot be stored inside the database, as the database is readonly. So it is stored inside a configuration JSON file under ''/home/root/standby.conf''. 
This configuration is backed up as usual by a Devices backup job and can be also manually restored on a standby (not on a primary though!).

Configuration options from the primary are not synced to the standby server, as the standby server has its own configuration (as it could be in a different network etc.)!

=== No automatic failover ===

There is currently no automatic failover mechanism. PostgreSQL doesn't offer multi master replication, so writing is just possible on the primary itself. Standby servers have a readonly database. 
Let's consider the following use case if we would implement an automatic failover with the current technical possibilities: 
* The primary server is connected to a master PBX.
* A slave PBX is also connected to the primary server in another location.
* A standby server is in this location and replicates from the primary.
* The internet connection between primary and standby fails.
* The standby promotes itself to primary, so that the master PBX now writes to the old primary and the slave PBX now writes to the "new" primary.
* The internet connection comes up again and both primary and standby servers now have databases which are out of sync and which cannot be merged.

=== Security ===

* port 5432 must be reachable on the App Platform
* For every standby a PostgreSQL user is created with the REPLICATION role on the primary. Just this user has access to the database server from non localhost connections.
* You cannot establish a standard connection with such a user and modify/read from tables.
* The replication connection is established over TLS by default.

= App Installer PBX Manager Plugin =
== Requirements ==

* V14 and above

== General ==

The app installer plugin allows IT administrator (with access to the PBX Manager) to install/update/delete new apps from the innovaphone app store including Partners apps. It is automatically available with existing app platforms or after adding a new one in the PBX Manager.
It offers a view to the App Platform Manager‘s App Store with all the available functionalities and simplifies the install, update and uninstall of apps.

== Dedicated AP for each user ==

Installing a new app will install the app service and add a new instance with the user’s domain. The instance is automatically started. 
This further enables the configuration of the instance through its respective PBX Manager plugin. 
Uninstalling the app will remove the app service and the corresponding instance.

== Shared AP between users ==

Installing a new app works in a similar way to that of the dedicated AP. However, each time a new user installs the app, only a new instance is created if the app service is already installed. 
A user can uninstall the app, in this case the corresponding instance is deleted. If no more instances exist, then the app service is uninstalled. 
The administrator can only update the app service in such scenario.

= Known Issues =

== Reboot after an image update hangs (ARM gateway) ==

If it happens, that the App Platform doesn't recover after the reboot, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
If '''Kernel command line''' is set to '''/dev/ram0''', the App Platform booted the ramdisk. 
 
Try to fetch the upgrade log file:
https://[APP-PLATFROM-IP/DNS]/manager/ramdisk.log
 
If this doesn't work, try to login with putty in this case (default credentials admin/ipapps and root/iplinux) and issue this command: 
''cat /apps/install_step1.log'' 
 
If this file contains '''finished''' at the end, you can reconfigure the settings under App Platform -> General: 
* press '''Stop'''
* Initrd file: empty
* Kernel command line: '''root=/dev/sda3'''
* Ramdisk size: empty
* press '''Start'''

The App Platform should boot and run the already updated image.

<pre style="color: red; font-size:150%;">---WARNING---
If the file doesn't contain "finished" at the end, you may still need to wait, as an upgrade may take some time!
Do not reconfigure without being sure that the upgrade has finished, otherwise your system may won't run!</pre>

== Reboot after an image update boots always into rescue mode (virtual machine) ==

This most likely means that the image installation didn't finish the first time and was interrupted before the bootloader settings could be changed back to the default partition. 
 
If your App Platform doesn't boot or isn't normally accessible after manual selection of the standard entry in the boot menu, you need to '''revert''' to a '''snapshot/backup''' prior to the update. 
If your App Platform runs normally though, you can follow this instruction to change the default boot entry: 
 
* boot into the '''rescue''' partition
* login with root/iplinux
* edit the file /boot/grub/grub.cfg
** search the line with '''set default=0''' and change it to '''set default=1'''
** reboot

== Reboot after an image update doesn't start as update is already running ==

If it happens, that the App Platform doesn't want to start an update because one is already running, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
* '''Shutdown''' the App Platform and '''Stop''' it. 
* Set '''Kernel command line''' to '''/dev/ram0'''. 
* Set '''Initrd file''' to '''ramdisk.ext2.xz'''. 
* Set '''Ramdisk size''' to '''100000'''. 
* '''Start''' the App Platform now. 

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

== Webserver doesn't respond after an image update ==

If you can't reach the web UI after an image update, please try to connect with SSH as admin user and delete old coredumps, which may prevent the App Platform Manager from starting correctly:
* su root (become root)
* rm -f /mnt/sda2/log/core_dumps/*/*
* /etc/init.d/S92manager restart

Check if you can now reach the App Platform again.

= Tracing =
Each App Service has its own log file, which can be accessed through the Manager App. You can configure a log file size for each App Service. 
Each App Intance has its own trace flags. The following trace flags can be set: 

* Alarm client: used by the manager to send alarms to an alarm server
* App: logs from the App Service itself
* App WebSocket: logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
* AppSharing: just native clients
* AppProxy: just native clients, logs requests which are proxied between the local webserver and the remote server
* Audio: just native clients
* Browser: just native clients
* Command: the command interface is used to execute shell commands, e.g. used by the manager App
* Config: logs config changes of an App
* Database: database logs
* DB files: database file logs
* DNS: DNS request logging
* DTLS: just native clients, DTLS request logging
* Ethernet: interface to get ethernet adapater infos, just manager App
* File: logs for file system access (synchronous), e.g. manager App
* Files: logs for file system access (asynchronous)
* HTTP client: http client logs
* HTTP file: logs for static HTTP files
* ICE: just native clients
* LDS: local domain sockets
* Media: just native clients
* Media channel: just native clients
* Process: IProcess interface logs which is used for spawning, killing processes etc.
* SMTP: SMTP client logs
* TCP: TCP logs
* Time: ITime interface logs
* TLS: TLS logs
* TURN: just native clients
* UDP: UDP logs
* Video: just native clients
* WebSocket client: logs outgoing websocket connections
* Webserver traffic: logs incoming HTTP traffic, which is forwarded from the webserver to the App
* WebDAV service: logs WebDAV requests to the App
* Webserver: enables webserver specific logs

== RPCAP ==

If you open the Manager App, click on the Manager in the left list and then on the Diagnostics button, you can enable RPCAP. 
You can add the interface in wireshark with the string:
rpcap://<APP-Platform-IP>/eth0

'''Please don't forget to disable RPCAP after your testing!'''

= How-Tos =

== How to retrieve files from the App Platform ==
To retrieve files from the App Platform which can not be retrieved via the App Platform manager UI, you can connect to the App Platform using the SCP protocol on port 22. 
 
First copy files to /home/admin as root with Putty or another SSH client:
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''su root'' to be root (''iplinux'' as default password)
 
You can now copy files to ''/home/admin'' (e.g. from /var/log/apps/manager/...). 
 
You can create a tar archive with all logs like this:
* cd /home/admin
* tar -cf - /var/log/* | xz -z - > log.tar.xz
** you may want to exclude coredumps (due to their size):
** tar -cf - --exclude=/var/log/core_dumps/* /var/log/* | xz -z - > log.tar.xz
* chown admin:admin /home/admin/log.tar.xz
 
Then copy the files to your local system, e.g. with WinSCP 
* use ''SCP'' as protocol (NB: WebDAV is not supported on most of the directories on the App Platform )
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''/home/admin'' as start directory
* copy the needed files

== App Platform disk space warning ==

If the configured threshold is reached, all Apps are stopped inside the App Platform . You must then free disk space somehow.

=== Find large instances ===
Click through your apps in the tree on the left side and take a look at the database size of each instance.

=== Delete data inside an instance ===
It depends on the type of app if you can delete data or not. E.g. you can start the Files app and delete files inside this app. 
This won't reclaim disk space though due to the way how PostgreSQL databases work, so you need to follow this guide to reclaim the disk space:

* start the corresponding App
* delete data inside the App
* optimize disk usage of the database by cliking on the button "Clean up database" under Edit instance. If this does not help, continue with the following steps.
* stop the corresponding App again
* download a backup of the instance (backup button at the top), this backup contains the whole instance data, also the password of the instance
* delete this specific instance
* restore the downloaded backup (restore button at the top)

Depending on the hardware and the size of the instance, this process may take hours to complete!

=== Resize the disk ===
The resizing of a disk is just possible for virtual machines, see [[#Resizing the disk of a Virtual machine|Resizing the disk of a Virtual machine]].

=== Delete the whole instance ===
If there is no other possibility, you can delete the whole instance. Afterwards you recreate the instance with the same values and a new random password. Don't forget to set this password in the corresponding PBX App objects though!

=== Restart the Apps or the App Platform ===
If you have enough disk space again, you must either restart the whole App Platform or you manually start all Apps again.

== App Platform/Apps app not online anymore due to full disk ==
If the apps app is not online anymore and you can't access any apps anymore, try to login with an SSH client to see if your disk is full.
Login as admin and afterwards as root (su root). 
 
* issue '''df -h''' and see the disk usage of /dev/sda2, if this is 100%, your disk is too full
* stop the manager
** /etc/init.d/S92manager stop
* empty the 500 MB file, which is exactly for this case here (manager must be 13r1 SR9 or higher to have this file)
** echo "" > /mnt/sda2/empty_if_no_space
* delete log files to recover some space
** rm /var/log/apps/*/*
** rm /var/log/core_dumps/*/*
* restart the postgresql server (see the output if this worked or not)
** /etc/init.d/S50postgresql restart
* restart the manager
** /etc/init.d/S92manager restart
* wait until everything is online again
* open the Apps app and try to find the instance which uses the most disk space and try to delete files/content from it
** you may want to stop all app services first to prevent more writes to the database
** if not possible, you can delete this instance, but you'll loose all data from this instance then!
* after that you can try [[{{NAMESPACE}}:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files]] to free up space
** If this does not work you can create a backup from the database, delete the database and import the database again.
* free up at least 500 MB so that the manager can create the file again
* delete /mnt/sda2/empty_if_no_space if you are done and restart the manager:
** rm /mnt/sda2/empty_if_no_space
** /etc/init.d/S92manager restart
** the manager restart automatically recreates the empty_if_no_space file if this file doesn't exist

Make sure, that you do '''not''' have backups configured to a local files instance while this files instance is not excluded from backups.
An instance can be excluded from backups in the instance settings in the App Platform Manager.

If all of this doesn't help, you can resize the file system on a VM:
* proceed with [[{{NAMESPACE}}:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine]]

== Resizing the disk of a Virtual machine ==

Do '''NOT''' resize if you're running an App Platform version higher than '''110000''' and lower than '''110027''' or '''130007''' and lower than '''130015''' or your data will be lost!
Please update your App Platform to version 130015 or higher before you start resizing your disk.

* stop the VM
* expand the disk using your VM utilities
* start the VM and boot from the first boot entry '''rescue/setup'''
* login with '''root''' and '''iplinux'''
* execute this command: '''/home/root/install_step1.sh log.txt resize'''
* the VM reboots automatically after a successful resize

== Shrink the physically size of PostgreSQL database files ==
Tuples that are deleted in your database are not physically removed from the database-file. So the claimed space on the harddisk is still in use after the delete operation.
If you need to free up some disk space you can force to reorganize the physically database-file on your harddisk.

You can also start this process through the instance settings as long as the App Platform Manager is still running.

'''Important: You are operating on the Database, you have to make a Backup of your Database before you do this!'''

Login via SSH to the APPlatform with the ''admin'' User
su root
/etc/init.d/S92manager stop # not always needed, but in case of database errors recommended, of course no app is online then
sudo -u postgres reindexdb -a
sudo -u postgres vacuumdb -a -f
/etc/init.d/S92manager restart # just execute if the manager has been stopped above

sudo -u postgres reindexdb -d dbname # for a single database with dbname
sudo -u postgres vacuumdb -d dbname -f # for a single database with dbname

Note: This may take some time and CDRs (or other data written to a DB) won't be received during this time.

After the process you can check the free dispace via <code>df -h</code>. You can check the claimed space from the database file with the command <code>du -sh /mnt/sda2/pgsql/</code>.

== Change IP Addresses / DNS Names / System Name ==

If you want to change the System Name or the DNS Name of the PBX and/or App Platform Platform you must change records manually '''in the described order'''!
You have to know the Admin password to directly Login to the App Platform .

=== App Platform ===
; Settings - General
* ''Devices app URL''
* ''App platform DNS name''

; Settings - Alarms and Events
* ''URL''

; All Instances
* ''Domain''
* ''Webserver path''

=== PBX ===
Download the configuration and ''search/replace'' in the config file. Upload the config file and reboot.

Manual:
* ''URL'' in all PBX Object (Apps, Voicemail ...)
* [[{{NAMESPACE}}:Gateway/CDR|CDRx]]
* [[{{NAMESPACE}}:PBX/Config/General|IP address for App Platform]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reset Password Page]]
* [[{{NAMESPACE}}:PBX/Config/Authentication|Verification link]]

Depending on your change you have to activate/deactivate the Setting [[{{NAMESPACE}}:PBX/Config/General|Operation without DNS]]

=== Additional Devices / Steps ===
* ''Devices Registration URL''
** There is no automatism to change the URL on all devices in your setup.
** If you have the option to use DHCP, you can temporarily overwrite the [[{{NAMESPACE}}:Services/Update|Update URL]] and execute a [[{{NAMESPACE}}:Concept_Update_Server|custom update script]] to change the ''Device Registration URL''
* ''Alarm server''
* Reverse Proxy configuration
* Change ''Domain Name'' in Devices if you have also changed the system name

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

initial error at 1500329378: ext4_journal_start_sb:328
last error at 1500329378: ext4_journal_start_sb:328

Or you get events like "Broken file system" from your App Platform .

This indicates a file system failure on the Linux Installation.

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

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

=== Gateway ===

* Open the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the Kernel command line from root=/dev/sda3 to root=/dev/ram0
** modify the Initrd file to ramdisk.ext2.xz
** modify the ramdisk size to 100000
** start Linux again
:: This will run Linux on another (hopefully sane) partition.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system

* go back to the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/ram0'' to <code>root=/dev/sda3</code>
** clear the Initrd file field
** clear the ramdisk size field
** start Linux again
:: This will run Linux on the original partition.

=== VM ===

Restart the VM and select the first entry in the boot menu from grub.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system
* Reboot your VM
[[Category:Concept]]

== How to create a memory dump of a running process ==

Sometimes it's usefull to have a memory dump of a running process to investigate certain issues.

* login with SSH and become root
* find out the PID of the relevant process, e.g. with ''ps aux | grep /apps/manager/manager | grep -v grep''
* gdb --pid PID -ex gcore --batch
* this creates a core file core.PID
* download this core file with WinSCP or similar tools

Reference13r1:Concept App Platform

2025-08-14T07:07:58Z

Dde: /* Resizing the disk of a Virtual machine */

Reference13r2:Concept App Platform

2025-08-14T07:07:48Z

Dde: /* Resizing the disk of a Virtual machine */

Reference13r3:Concept App Platform

2025-08-14T07:07:32Z

Dde: /* Resizing the disk of a Virtual machine */

= General =
* V13 uses [https://buildroot.org/ buildroot]
* this is an own (innovaphone) collection of packages
* For further information see: [https://buildroot.org/docs.html Buildroot Documentations]

== Requirements ==

* V13 or up
* Gateway (arm): IPx10 (with CF card) or IPx11 (with mSATA SSD)
* Gateway (arm64): IPx13 (with m2 SSD)
* Virtual (x86_64)
** HyperV with [https://docs.microsoft.com/de-de/windows-server/virtualization/hyper-v/deploy/upgrade-virtual-machine-version-in-hyper-v-on-windows-or-windows-server#supported-virtual-machine-configuration-versions VM-configuration Version] 6.2 (minimum: Windows 10 or Windows Server 2016)
** VMWare

== Default credentials ==

'''During INSTALL, the default passwords are replaced with the global Admin PW!'''
* SSH-Login with '''admin''' and '''ipapps'''
* root login with '''root''' and '''iplinux''' (the root login is not directly possible, you have to login as admin first and use the command ''su root'')
* manager App (web login) '''pwd'''

= App Platform - arm/arm64 (Gateway)=

* The installation image has a size of ~50MB. During installation, the following partitions are created<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 fat32: 200MB (contains ramdisk, rootfs and kernel)
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB

When comparing potential performance of the IPxx11 platform compared to the IPxx10 platform, there are some major differences:
* SSDs found in the xx11 are faster and more reliable than the CF found in the xx10
* the available RAM for the App Platform (as specified in column ''RAM for LAP (GB) out of RAM'' in chapter ''Technical data and recommended number of users supported'' of [[Howto:How_to_implement_large_PBXs#Technical_data_and_recommended_number_of_users_supported|How to implement large PBXs]]) is factor 6 larger on the xx11 (1,536 GB) than on the xx10 (0,256 GB))
* the xx11 has gigabit Ethernet while the xx10 has 100Mbps Ethernet. The xx10 is therefore not well suited for Apps with larger network traffic, such as Recordings
* the CPU of the xx11 (although it runs on the same frequency) is roughly 20% faster than the xx10

While it is hard to predict the performance of the App Platform in a specific scenario, we see that in a real life environment an App Platform running on an xx11 platform can well support 150 users. The xx10 platform is estimated to support 120 users. Because CPU performance is the limiting factor, larger setups can be built based on the virtual machine platform (see [[#App_services_and_multi-threading|App services and multi-threading]] below).

<references/>

= App Platform - x86-64 (Virtual Machine 64bit) =

* The default disk size is 16GB. It should be increased '''before''' the first start if needed!
* Multiple CPUs are supported, default is one CPU
* default RAM: 512MB
* static IP address, DNS, Gateway can be configured with the command '''setip''' on the console. Run '''setip --help''' to get a list of parameters. (Example: setip --addr=x.x.x.x --mask=x.x.x.x --gateway=x.x.x.x --dns1=x.x.x.x)
* If you have permission problems change to su user (Password is iplinux or your new admin password)
* To figure out your ip address you can use the command: ''ip address'' on the console.
* '''loadkeys de''' can be used to change to german keyboard layout (etc.)
* partitions<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 ext2: 350MB (contains ramdisk, rootfs and kernel)
*** the real partition format size is smaller but there is no need to monitor sda1 as sda1 won't grow during usage of the App Platform
*** sda1 is completely exchanged during an image update and its size might have changed but will never exceed these 350MB
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB
* VMWare Tools: Open VM Tools
* Qemu Guest Agent: installed since 110032
** The qemu guest agent can be configured in Proxmox with ''Virtio'' or ''ISA''. You '''must''' use '''ISA''', as Virtio is currently not supported.

<references/>

= Installation =
==ARM Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-armel.img'' image file.
* The installation runs without any further required step.

==ARM64 Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-arm64.img'' image file.
* The installation runs without any further required step.

==Virtual machine==

* Import the image into your server environment.
* Edit the disk size, if needed.
* Start the machine and wait until it reboots and starts again.
* Note: If you need to access an IP addresses available through a VPN connection from from inside the virtual machine, it could be that you need to set the network of your VM to NAT (and also add the URL for an IP to /etc/hosts)

[https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Configuration More Configuration Hints regarding VM Ware]

== Backup of the Apps ==

Each App Service can have multiple instances and each instance has its own database. The manager app itself also has its own database. 
There are no other files which need to be backuped. 
The standard way to backup the databases is through the Devices App [[{{NAMESPACE}}:Concept_App_Service_Devices#Backups]]. 
 
An alternate way is to use a command file which is similar to the command files from the firmware.

===Commands===
* '''times''' 0,12 # backup only at 0 or 12 o'clock
* '''backup-instances''' http://user:pw@ip/path/#I-#D.dump PUT
** PUT and POST are supported, all instances including the manager itself are saved
* '''backup-instance''' http://user:pw@ip/path/#I-#D.dump apidemo example.com PUT
** backup a single instance with instance name and instance domain
* '''backup-manager''' http://user:pw@ip/path/#I-#D.dump

===Hash parameters===
* #L App Platform label (neu), e.g. 10024
* #A App label (neu), e.g. 130004
* #I instance name (neu), e.g. reporting1
* #D instance domain (neu), e.g. innovaphone.com
* #m MAC address of the LAP, e.g. 00ab11eeff
* #d Current date and time (plain UTC without daylight saving and timezone adjustments) 20051010-170130
* #bn rolling backup index (n >=0 and <= 9, just one digit)
* ## escapes a hash mark

= App Platform Infrastructure and Concept =
== Webserver ==
The app platform includes a webserver that is highly optimized for handling many Websocket connections at a low memory footprint.
All apps use that webserver by registering for specific HTTP subpath. So they can all use the same HTTP/HTTPS ports - typically the standard ports.

=== Import Custom SSL Certificate ===
You have to upload a PEM Certificate with the following chain structure and without password encoding.

-----BEGIN CERTIFICATE-----
(certificate: your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: your_domain_name.key)
-----END RSA PRIVATE KEY-----

If you have problems generating the complete and correct certificate chain, you can use tools such as https://whatsmychaincert.com/ as an aid.
'''Please keep in mind that you never give away the private part of your key.'''

=== Known issues ===
*The app platform webserver can use only the default http/https ports 80/443.
*By design, there is no possibility to restore the default webserver certificate on the App Platform, if another certificate was once uploaded. 
**If nevertheless needed, you must login with Putty (see [[#How_to_retrieve_files_from_the_AP | Retrieve files]]) and execute these commands as root:
**''psql -d manager -c "DELETE FROM config WHERE name='webserverCertificate'"''
**''/etc/init.d/S92manager restart''
*The app platform webserver interprets URLs case-sensitive. In other words, <nowiki>http://<addr>/file.txt</nowiki> is not the same as <nowiki>http://<addr>/FILE.TXT</nowiki>

== Database ==
The app platform creates a database for each app instance with a given password. In the installer there will be used randomly generated passwords. You can set a new database password for every instance in the Application Platform.

The apps should store all data in that database. That makes sure that a consistent backup and restore of app instances can be done by the app platform manager.
In hosted scenarios, having separate databases for each instance also makes sure that the data of different customers are clearly separated and can easily be moved from one physical platform to another.

The default configuration decline database request from extern. If you need external access you can change the PGSQL configuration (as root) in the file ''/mnt/sda2/pgsql/pg_hba.conf''.
After editing pg_hba.conf, the database-service has to be restarted with the command <code>/etc/init.d/S50postgresql restart</code>
(Please think about it before you do it, because a better way is to create your own local app with local database access.)

You can find the official documentation for the pg_hba.conf here: https://www.postgresql.org/docs/14/auth-pg-hba-conf.html

Please note that you do this on your own responsibility, that it makes sense to create a backup of the original pg_hba.conf
and that you may break your database server if you do not know exactly what you do!

Sometimes the Apps are not proper working after this. You can wait a while until everything is working again or you go the hard way:
* stop the manager
** <code>/etc/init.d/S92manager stop</code>
* restart the database-service (maybe not really necessary, but makes a good feeling)
**<code>/etc/init.d/S50postgresql restart</code>
* start the manager
** <code>/etc/init.d/S92manager start</code>

== App Platform Manager ==
The App Platform Manager is the central component of the App Platform. It does the following:
* Installing app services by downloading the binaries from an app store.
* Running and monitoring app services. If an app service crashes it is restarted, automatically.
* Management of app instances and providing them with the environment they need:
** A database
** A webserver path
** A password for authentication
* Backup and restore of app instances.
* Collecting debug information like tracing and crash dumps.
* System monitoring (CPU usage, memory usage, etc).

== App Services ==
App services are runned by the App Platform Manager. They implement an interface that is used by the manager to start, stop and configure app instances. Each service runs in a separate child process of the manager.

== App Instances ==
The actual functionality of an app service is provided by app instances. They run in the same process as the app service but have a distinct webserver path and their own database. There can be 0..n instances of an app service. Instances can optionally host (web) apps that can be opened in the myApps client.

Each instance of an App service has two passwords. The instance password itself and a database password. If you want to change it you must update the password on both sides. 
The instance password must match to the password in the corresponding PBX App objects, while one instance can have different App objects. 
The database password must be just known to the manager and not outside of the App Platform.

The ''Database name'' and ''Database user'' are both limited to a length of 63 characters. By default, the App Manager would create ''<domain>''_''<instance-name>'' as value for both. This is why it is recommended to use instance names so that length(name) + length(domain) is less than 63 characters. However, if this is not possible, you can manually shorten the suggested values (both must still be unique on your App Platform).

=== Cleanup database ===
You can cleanup the instance database inside the instance settings. This starts the vacuumdb process for the instance database which frees disk space of deleted rows.
Note that this process locks the database and that sufficient disk space is needed to complete it!

=== External database host ===
You can optionally configure an external database host, if the database shall be hosted on an external host. 
Note that the App Platform Manager still creates a local database, which is then not used as long as the external host is configured.

What are external databases useful for?:
* User data is too large (files are stored as BLOB in the database)
* Other (non-innovaphone) database servers are to be used due to other regulations
* There is already an external database cluster with its own backup/restore processes which should be used
* More performance is required (please note that a local UNIX socket provides much faster results than a remote database server). Depending on the app and the task of the app, it can still be useful to use a separate server if it is faster.

==== Supported database types ====
In principle, ''PostgreSQL'' and ''MySQL'' are supported. However, please note that the respective app must be designed for the target database server type. If an app has been developed for PostgreSQL, it cannot be operated on a MySQL server.

'''Please note:''' All innovaphone apps are developed exclusively as PostgreSQL apps.

MySQL therefore only makes sense if own apps are developed and MySQL or certain MySQL features are to be used. For such apps, it is very important to deactivate the automatic Application Platform APP-Backup.
The database backup process of the App Platform uses PostgreSQL backup commands, which is why the backup would fail, so the app must be excluded from the backup, and you must take care of the backup yourself.

==== Database creation ====
If you use an external database, you have to create the database itself.
The App Platform Manager itself creates a PostgreSQL database like this (you may respect this on your database host to be compatible with the database implementation inside the Apps):
* CREATE DATABASE "dbname" ENCODING 'UTF8';
* CREATE USER "dbuser";
* ALTER USER "dbuser" WITH PASSWORD 'dbpassword';
* GRANT ALL PRIVILEGES ON DATABASE "dbname" TO "dbuser";
* ALTER DATABASE "dbname" OWNER TO "dbuser";
* REVOKE CONNECT ON DATABASE "dbname" FROM public;

==== Database connection ====
There are different possibilities to specify the host. You can use a DNS-Name, IPv4 or IPv6. A port can be optionally added with a colon.

Our PostgreSQL implementation sets sslmode=prefer, so SSL is used by default if enabled on the server.

==== Backup/Restore ====
External databases are still backuped as normal, but you can't restore such a database with the App Platform Manager on the external host! You must restore such a dump manually on your database host.

==== Database redundancy ====
In principle, it is possible to create redundancies for failure scenarios through this function.

However, there are different scenarios that need to be evaluated on a case-by-case basis:

* One database, multiple App Platforms (primary online / secondary '''offline''') where multiple apps access the same database.
** This mode of operation is legal as long as you can really ensure that only one App Platform is active at a time.

* One database, multiple App Platforms (primary online / secondary '''online''') with multiple apps accessing the same database.
** This operating mode cannot be used for innovaphone apps, as the app itself would have to be developed for such a mode, which it is not.

However, we advise great caution here! The use of the same databases from different nodes may only be used if you can ensure that the databases or runtime environments of apps cannot get into a ''split-brain'' mode.

== Relationship between app instances and app objects in the PBX ==
Typically an app instance is connected to one or more app objects in a customer PBX. This is done by configuring the same parameters on both sides:
* URL
* Password
The password is used by the PBX for authenticating itself, users and services against the app instance.

Some apps need a websocket connection with the PBX. When "websocket" is activated at the app object, the PBX establishes a websocket connection to the app instance and provides the APIs that are configured at the app object.

=== Supported scenarios ===
It is important to understand that the concept does not do any assumptions on how PBXes and APs are correlated. So you can have
* One App Platform for one customer
* One App Platform for many customers
* Many App Platforms for one customer
* Many App Platforms for many customers

Attention: The V13 installer can only configure the scenario "''One App Platform for one customer''". If you want to have a different scenario, you have to configure it manually.

For hosting or cloud scenarios you need special scenarios. Please refer our [[Howto:V13_Hosting| V13 Hosting]] instructions.

=== Restrictions ===
Currently we don't have redundancy for app instances or App Platforms.

== Update of the App Platform itself ==
The App Platform is build on top of buildroot and will receive updates and fixes from time to time. 
You can update the used build inside the Manager App by using the '''Update''' button at the top. 

It is strongly advised to make a full backup (VM) or at least backup all apps (Gateway) before you run such an update!

== App services and multi-threading ==
Each App Service runs in a single process with no multi-threading, independent of the instances of the App Service. However, each instance maintains its own database connection and the database responds to this connect with the creation of a new process. Each app service therefore uses 1+''n'' threads (where ''n'' is the number of instances). All communication between app service instances and their clients must pass the single-threaded web server. On platforms with multi-threading support (i.e. VMware or Hyper-V), up to 1 + ''m'' + ''m'' * ''n'' (with ''m'' being the number of Apps and ''n'' the number of instances per App) threads can be utilized.

= AP Manager settings =

== General ==
* ''Enable Developer mode'': in developer mode, apps can be manually uploaded without an App Store
* ''Disable App security'': each App has an own unix user and if this flag is set, the user can login with SSH for debugging
* ''App Store URL'': the URL to the App Store where Apps are searched and also an update of the AP image itself
* ''Devices app URL'': the URL to the Devices App to manage the AP through Devices
* ''Devices app URL 2'': don't use!
* ''App Platform DNS name'': currently not used
* ''NTP server 1/2'': NTP servers for this AP (in addition to NTP servers retrieved by DHCP)
* ''Timezone string'':
* ''DNS server 1/2'': DNS servers for this AP (in addition to DNS servers retrieved by DHCP)
* ''Database optimization time'': The database optimization process will be started at this hour (local time), with a random offset of up to 7 hours
* ''Command file'': obsolete, use the Devices App for backups!

== Security ==
* ''Webserver certificate'': upload a webserver certificate in PEM format
* ''AP Manager password'': the password to the web interface of the AP Manager (normally set through Devices)
* ''Linux root user'': password of the root user (normally set through Devices)
* ''Linux admin user'': password of the admin user (normally set through Devices)

== Alarms and events ==
* ''URL'': URL to the Events app
* ''Username/Password'': HTTP credentials of the Events app
* ''Email address'': an email address which will get emails on full disk alarms/warnings
* ''Threshold'': All Apps will be stopped and an hourly email sent on reaching this threshold. An alarm is generated 10% before reaching this threshold and an email is sent every 24 hours.

== SMTP ==
SMTP server settings for sending emails from within the AP Manager.

== Registered Access Domains ==

= App Platform replication =

== Requirements ==

* 13r3 on both standby servers and the primary server
* at least an App Platform image starting with version 110002 (otherwise postgresql is too old)
* standby and primary servers must have the same system architecture
** arm gateways (IPx11) just with arm gateways (IPx11)
** arm64 gateways (IPx13) just with arm64 gateways (IPx13)
** x86_64 virtual machines just with x86_64 virtual machines
* the disk size on standby servers must be at least equal as the disk size on the primary server

== General ==
The configuration is done within the App Platform Manager next to the settings button under "Replication".

=== Off ===
No replication is done at all.

=== Primary ===
The App Platform acts as primary server for one or multiple standby servers. 
Max 8 standby servers can be configured. 
 
Every standby server must get a unique name on the primary server which is then also configured on the standby server itself. This is due to the fact, that the primary server preserves data for every standby server while it's not reachable. 
A standby server name must be a valid domain name, although this name is currently not used as DNS name (but might be used in the future). 
 
The password is randomly pregenerated and must be used as handed by the App Platform Manager.

==== PostgreSQL port ====
The default PostgreSQL port is 5432 and can't be changed on the primary. It must be reachable through your firewall or at least forwarded on a different port towards this App Platform on port 5432.

=== Standby ===
Configure the password from the primary and one of the not yet used standby server names. 
The host and port must be reachable through the network. You can specify a non default port which then must be forwarded somewhere else to port 5432 on your primary.

*Note: Do '''not''' configure the same standby name on different standby servers, as this will break the replication on at least one standby! 
*Note: On a standby, all '''locally installed apps are removed''' during installation

== Failure detection ==

The replication state on both primary and standby servers are continuously monitored. 
In case of a broken connection, an alarm is triggered at once and just cleared if the failure goes away. 
 
If such an alarm lasts for 5 minutes an email is send. The recipient address must be configured in the App Platform Manager settings under "Alarms and Events" and you must also provide a valid SMTP configuration.

== Failover ==

There is no automatic failover procedure. If you detect the failure state, you must get active yourself.

=== Standby down ===

Fix the standby server and see if the replication comes up again. If not, setup a new standby server which will replicate the whole database cluster from scratch.

=== Primary down ===

If the primary is down and cannot be brought into life again, you must take the following steps, depending on your configuration:

==== One standby server ====

* Disable the replication in the replication configuration. You will then have a standalone App Platform afterwards.

==== Multiple standby servers ====

* Change the replication type on one of the standby servers from standby to primary. Please note that the other standby entries must still exist here (they are automatically offered)!
* Change the host entry on the other standby servers to the new standby server. The standby server will sync the whole database cluster again, which will take time.

==== Configuration changes ====

You must also tell the PBXes and other tools to use the new primary server.

* You may simply change the IP address behind the DNS of your primary server to point to the new primary server.
* Without DNS, you must currently modify the configuration by replacing the IP address of the old primary with the new address.
** This must be done in every master PBX configuration.
** This must be done in every App configuration which may use this IP address, e.g. Devices which rolls out an alarm server configuration

== App Platfom update ==

If you're running an active standby server and the major version of the PostgreSQL database didn't change, you can simply update primary and standby servers independently. 
 
If it contains a ''new major version'' of the PostgreSQL database, you must follow these steps:

* deactivate replication on all standby servers (which promotes these standby servers to active servers)
* ensure that the '''same''' App Platform Manager version is running on primary and standby servers!
* perform the App Platform update on the primary server
* perform the App Platform update on the standby servers
* reactivate replication on the standby servers (which will do a full replication again, so it might take some time)

Alternativly you may setup the standby server from scratch directly with the new App Platform image version.

Sadly there is currently no better method offered by PostgreSQL to perform such an upgrade.

== Technical backgrounds ==

=== Streaming replication ===

We use the asynchronous [https://www.postgresql.org/docs/9.3/warm-standby.html#STREAMING-REPLICATION streaming replication of PostgreSQL]. A transaction thus just waits for a commit on the primary server. Standby servers will receive the transaction asynchronously afterwards to avoid a reduced writing performance. 
A primary server keeps the neccessary WAL files for every standby server until the standby fetched the neccessary information. 
This fact can lead to higher disk space usage on the primary if one or multiple standby servers are offline for a while.

Take care to fix broken replications as soon as possible to avoid a full disk on the primary server!

=== What is replicated ===
The whole database cluster of an app platform is replicated. This includes every database of every instance and the database of the App Platform Manager itself. 

=== App Services on standbys ===
The database of the App Platform Manager itself also contains the App service binaries to be able to restore applications in a failover case. 
You do not have to install App services on the standby if you install them on the primary. 
App Platform Manager and Webserver can be updated as usual through the App Store or the Devices App if the standby is connected to Devices.

=== App Platform Manager configuration of the standby server ===
The App Platform Manager configuration of the standby server cannot be stored inside the database, as the database is readonly. So it is stored inside a configuration JSON file under ''/home/root/standby.conf''. 
This configuration is backed up as usual by a Devices backup job and can be also manually restored on a standby (not on a primary though!).

Configuration options from the primary are not synced to the standby server, as the standby server has its own configuration (as it could be in a different network etc.)!

=== No automatic failover ===

There is currently no automatic failover mechanism. PostgreSQL doesn't offer multi master replication, so writing is just possible on the primary itself. Standby servers have a readonly database. 
Let's consider the following use case if we would implement an automatic failover with the current technical possibilities: 
* The primary server is connected to a master PBX.
* A slave PBX is also connected to the primary server in another location.
* A standby server is in this location and replicates from the primary.
* The internet connection between primary and standby fails.
* The standby promotes itself to primary, so that the master PBX now writes to the old primary and the slave PBX now writes to the "new" primary.
* The internet connection comes up again and both primary and standby servers now have databases which are out of sync and which cannot be merged.

=== Security ===

* port 5432 must be reachable on the App Platform
* For every standby a PostgreSQL user is created with the REPLICATION role on the primary. Just this user has access to the database server from non localhost connections.
* You cannot establish a standard connection with such a user and modify/read from tables.
* The replication connection is established over TLS by default.

= Known Issues =

== Reboot after an image update hangs (ARM gateway) ==

If it happens, that the App Platform doesn't recover after the reboot, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
If '''Kernel command line''' is set to '''/dev/ram0''', the App Platform booted the ramdisk. 
 
Try to fetch the upgrade log file:
https://[APP-PLATFROM-IP/DNS]/manager/ramdisk.log
 
If this doesn't work, try to login with putty in this case (default credentials admin/ipapps and root/iplinux) and issue this command: 
''cat /apps/install_step1.log'' 
 
If this file contains '''finished''' at the end, you can reconfigure the settings under App Platform -> General: 
* press '''Stop'''
* Initrd file: empty
* Kernel command line: '''root=/dev/sda3'''
* Ramdisk size: empty
* press '''Start'''

The App Platform should boot and run the already updated image.

<pre style="color: red; font-size:150%;">---WARNING---
If the file doesn't contain "finished" at the end, you may still need to wait, as an upgrade may take some time!
Do not reconfigure without being sure that the upgrade has finished, otherwise your system may won't run!</pre>

== Reboot after an image update boots always into rescue mode (virtual machine) ==

This most likely means that the image installation didn't finish the first time and was interrupted before the bootloader settings could be changed back to the default partition. 
 
If your App Platform doesn't boot or isn't normally accessible after manual selection of the standard entry in the boot menu, you need to '''revert''' to a '''snapshot/backup''' prior to the update. 
If your App Platform runs normally though, you can follow this instruction to change the default boot entry: 
 
* boot into the '''rescue''' partition
* login with root/iplinux
* edit the file /boot/grub/grub.cfg
** search the line with '''set default=0''' and change it to '''set default=1'''
** reboot

== Reboot after an image update doesn't start as update is already running ==

If it happens, that the App Platform doesn't want to start an update because one is already running, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
* '''Shutdown''' the App Platform and '''Stop''' it. 
* Set '''Kernel command line''' to '''/dev/ram0'''. 
* Set '''Initrd file''' to '''ramdisk.ext2.xz'''. 
* Set '''Ramdisk size''' to '''100000'''. 
* '''Start''' the App Platform now. 

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

== Webserver doesn't respond after an image update ==

If you can't reach the web UI after an image update, please try to connect with SSH as admin user and delete old coredumps, which may prevent the App Platform Manager from starting correctly:
* su root (become root)
* rm -f /mnt/sda2/log/core_dumps/*/*
* /etc/init.d/S92manager restart

Check if you can now reach the App Platform again.

= Tracing =
Each App Service has its own log file, which can be accessed through the Manager App. You can configure a log file size for each App Service. 
Each App Intance has its own trace flags. The following trace flags can be set: 

* Alarm client: used by the manager to send alarms to an alarm server
* App: logs from the App Service itself
* App WebSocket: logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
* AppSharing: just native clients
* AppProxy: just native clients, logs requests which are proxied between the local webserver and the remote server
* Audio: just native clients
* Browser: just native clients
* Command: the command interface is used to execute shell commands, e.g. used by the manager App
* Config: logs config changes of an App
* Database: database logs
* DB files: database file logs
* DNS: DNS request logging
* DTLS: just native clients, DTLS request logging
* Ethernet: interface to get ethernet adapater infos, just manager App
* File: logs for file system access (synchronous), e.g. manager App
* Files: logs for file system access (asynchronous)
* HTTP client: http client logs
* HTTP file: logs for static HTTP files
* ICE: just native clients
* LDS: local domain sockets
* Media: just native clients
* Media channel: just native clients
* Process: IProcess interface logs which is used for spawning, killing processes etc.
* SMTP: SMTP client logs
* TCP: TCP logs
* Time: ITime interface logs
* TLS: TLS logs
* TURN: just native clients
* UDP: UDP logs
* Video: just native clients
* WebSocket client: logs outgoing websocket connections
* Webserver traffic: logs incoming HTTP traffic, which is forwarded from the webserver to the App
* WebDAV service: logs WebDAV requests to the App
* Webserver: enables webserver specific logs

== RPCAP ==

If you open the Manager App, click on the Manager in the left list and then on the Diagnostics button, you can enable RPCAP. 
You can add the interface in wireshark with the string:
rpcap://<APP-Platform-IP>/eth0

'''Please don't forget to disable RPCAP after your testing!'''

= How-Tos =

== How to retrieve files from the App Platform ==
To retrieve files from the App Platform which can not be retrieved via the App Platform manager UI, you can connect to the App Platform using the SCP protocol on port 22. 
 
First copy files to /home/admin as root with Putty or another SSH client:
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''su root'' to be root (''iplinux'' as default password)
 
You can now copy files to ''/home/admin'' (e.g. from /var/log/apps/manager/...). 
 
You can create a tar archive with all logs like this:
* cd /home/admin
* tar -cf - /var/log/* | xz -z - > log.tar.xz
** you may want to exclude coredumps (due to their size):
** tar -cf - --exclude=/var/log/core_dumps/* /var/log/* | xz -z - > log.tar.xz
* chown admin:admin /home/admin/log.tar.xz
 
Then copy the files to your local system, e.g. with WinSCP 
* use ''SCP'' as protocol (NB: WebDAV is not supported on most of the directories on the App Platform )
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''/home/admin'' as start directory
* copy the needed files

== App Platform disk space warning ==

If the configured threshold is reached, all Apps are stopped inside the App Platform . You must then free disk space somehow.

=== Find large instances ===
Click through your apps in the tree on the left side and take a look at the database size of each instance.

=== Delete data inside an instance ===
It depends on the type of app if you can delete data or not. E.g. you can start the Files app and delete files inside this app. 
This won't reclaim disk space though due to the way how PostgreSQL databases work, so you need to follow this guide to reclaim the disk space:

* start the corresponding App
* delete data inside the App
* optimize disk usage of the database by cliking on the button "Clean up database" under Edit instance. If this does not help, continue with the following steps.
* stop the corresponding App again
* download a backup of the instance (backup button at the top), this backup contains the whole instance data, also the password of the instance
* delete this specific instance
* restore the downloaded backup (restore button at the top)

Depending on the hardware and the size of the instance, this process may take hours to complete!

=== Resize the disk ===
The resizing of a disk is just possible for virtual machines, see [[#Resizing the disk of a Virtual machine|Resizing the disk of a Virtual machine]].

=== Delete the whole instance ===
If there is no other possibility, you can delete the whole instance. Afterwards you recreate the instance with the same values and a new random password. Don't forget to set this password in the corresponding PBX App objects though!

=== Restart the Apps or the App Platform ===
If you have enough disk space again, you must either restart the whole App Platform or you manually start all Apps again.

== App Platform/Apps app not online anymore due to full disk ==
If the apps app is not online anymore and you can't access any apps anymore, try to login with an SSH client to see if your disk is full.
Login as admin and afterwards as root (su root). 
 
* issue '''df -h''' and see the disk usage of /dev/sda2, if this is 100%, your disk is too full
* stop the manager
** /etc/init.d/S92manager stop
* empty the 500 MB file, which is exactly for this case here (manager must be 13r1 SR9 or higher to have this file)
** echo "" > /mnt/sda2/empty_if_no_space
* delete log files to recover some space
** rm /var/log/apps/*/*
** rm /var/log/core_dumps/*/*
* restart the postgresql server (see the output if this worked or not)
** /etc/init.d/S50postgresql restart
* restart the manager
** /etc/init.d/S92manager restart
* wait until everything is online again
* open the Apps app and try to find the instance which uses the most disk space and try to delete files/content from it
** you may want to stop all app services first to prevent more writes to the database
** if not possible, you can delete this instance, but you'll loose all data from this instance then!
* after that you can try [[{{NAMESPACE}}:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files]] to free up space
** If this does not work you can create a backup from the database, delete the database and import the database again.
* free up at least 500 MB so that the manager can create the file again
* delete /mnt/sda2/empty_if_no_space if you are done and restart the manager:
** rm /mnt/sda2/empty_if_no_space
** /etc/init.d/S92manager restart
** the manager restart automatically recreates the empty_if_no_space file if this file doesn't exist

Make sure, that you do '''not''' have backups configured to a local files instance while this files instance is not excluded from backups.
An instance can be excluded from backups in the instance settings in the App Platform Manager.

If all of this doesn't help, you can resize the file system on a VM:
* proceed with [[{{NAMESPACE}}:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine]]

== Resizing the disk of a Virtual machine ==

Do '''NOT''' resize if you're running an App Platform version higher than '''110000''' and lower than '''110027''' or '''130007''' and lower than '''130015''' or your data will be lost!
Please update your App Platform to version 130015 or higher before you start resizing your disk.

* stop the VM
* expand the disk using your VM utilities
* start the VM and boot from the first boot entry '''rescue/setup'''
* login with '''root''' and '''iplinux'''
* execute this command: '''/home/root/install_step1.sh log.txt resize'''
* the VM reboots automatically after a successful resize

== Shrink the physically size of PostgreSQL database files ==
Tuples that are deleted in your database are not physically removed from the database-file. So the claimed space on the harddisk is still in use after the delete operation.
If you need to free up some disk space you can force to reorganize the physically database-file on your harddisk.

You can also start this process through the instance settings as long as the App Platform Manager is still running.

'''Important: You are operating on the Database, you have to make a Backup of your Database before you do this!'''

Login via SSH to the APPlatform with the ''admin'' User
su root
/etc/init.d/S92manager stop # not always needed, but in case of database errors recommended, of course no app is online then
sudo -u postgres reindexdb -a
sudo -u postgres vacuumdb -a -f
/etc/init.d/S92manager restart # just execute if the manager has been stopped above

sudo -u postgres reindexdb -d dbname # for a single database with dbname
sudo -u postgres vacuumdb -d dbname -f # for a single database with dbname

Note: This may take some time and CDRs (or other data written to a DB) won't be received during this time.

After the process you can check the free dispace via <code>df -h</code>. You can check the claimed space from the database file with the command <code>du -sh /mnt/sda2/pgsql/</code>.

== Change IP Addresses / DNS Names / System Name ==

If you want to change the System Name or the DNS Name of the PBX and/or App Platform Platform you must change records manually '''in the described order'''!
You have to know the Admin password to directly Login to the App Platform .

=== App Platform ===
; Settings - General
* ''Devices app URL''
* ''App platform DNS name''

; Settings - Alarms and Events
* ''URL''

; All Instances
* ''Domain''
* ''Webserver path''

=== PBX ===
Download the configuration and ''search/replace'' in the config file. Upload the config file and reboot.

Manual:
* ''URL'' in all PBX Object (Apps, Voicemail ...)
* [[{{NAMESPACE}}:Gateway/CDR|CDRx]]
* [[{{NAMESPACE}}:PBX/Config/General|IP address for App Platform]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reset Password Page]]
* [[{{NAMESPACE}}:PBX/Config/Authentication|Verification link]]

Depending on your change you have to activate/deactivate the Setting [[{{NAMESPACE}}:PBX/Config/General|Operation without DNS]]

=== Additional Devices / Steps ===
* ''Devices Registration URL''
** There is no automatism to change the URL on all devices in your setup.
** If you have the option to use DHCP, you can temporarily overwrite the [[{{NAMESPACE}}:Services/Update|Update URL]] and execute a [[{{NAMESPACE}}:Concept_Update_Server|custom update script]] to change the ''Device Registration URL''
* ''Alarm server''
* Reverse Proxy configuration
* Change ''Domain Name'' in Devices if you have also changed the system name

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

initial error at 1500329378: ext4_journal_start_sb:328
last error at 1500329378: ext4_journal_start_sb:328

Or you get events like "Broken file system" from your App Platform .

This indicates a file system failure on the Linux Installation.

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

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

=== Gateway ===

* Open the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the Kernel command line from root=/dev/sda3 to root=/dev/ram0
** modify the Initrd file to ramdisk.ext2.xz
** modify the ramdisk size to 100000
** start Linux again
:: This will run Linux on another (hopefully sane) partition.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system

* go back to the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/ram0'' to <code>root=/dev/sda3</code>
** clear the Initrd file field
** clear the ramdisk size field
** start Linux again
:: This will run Linux on the original partition.

=== VM ===

Restart the VM and select the first entry in the boot menu from grub.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system
* Reboot your VM
[[Category:Concept]]

== How to create a memory dump of a running process ==

Sometimes it's usefull to have a memory dump of a running process to investigate certain issues.

* login with SSH and become root
* find out the PID of the relevant process, e.g. with ''ps aux | grep /apps/manager/manager | grep -v grep''
* gdb --pid PID -ex gcore --batch
* this creates a core file core.PID
* download this core file with WinSCP or similar tools

Reference14r2:Concept App Platform

2025-08-14T07:07:06Z

Dde: /* Resizing the disk of a Virtual machine */

= General =
* V13 uses [https://buildroot.org/ buildroot]
* this is an own (innovaphone) collection of packages
* For further information see: [https://buildroot.org/docs.html Buildroot Documentations]

== Requirements ==

* V13 or above
* Gateway (arm): IPx10 (with CF card) or IPx11 (with mSATA SSD)
* Gateway (arm64): IPx13 (with m2 SSD)
* Virtual (x86_64)
** HyperV with [https://docs.microsoft.com/de-de/windows-server/virtualization/hyper-v/deploy/upgrade-virtual-machine-version-in-hyper-v-on-windows-or-windows-server#supported-virtual-machine-configuration-versions VM-configuration Version] 6.2 (minimum: Windows 10 or Windows Server 2016)
** VMWare
** Proxmox/KVM/Qemu

== Default credentials ==

'''During INSTALL, the default passwords are replaced with the global Admin PW!'''
* SSH-Login with '''admin''' and '''ipapps'''
* root login with '''root''' and '''iplinux''' (the root login is not directly possible, you have to login as admin first and use the command ''su root'')
* manager App (web login) '''pwd'''

= App Platform - arm/arm64 (Gateway)=

* The installation image has a size of ~50MB. During installation, the following partitions are created<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 fat32: 200MB (contains ramdisk, rootfs and kernel)
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB

When comparing potential performance of the IPxx11 platform compared to the IPxx10 platform, there are some major differences:
* SSDs found in the xx11 are faster and more reliable than the CF found in the xx10
* the available RAM for the App Platform (as specified in column ''RAM for LAP (GB) out of RAM'' in chapter ''Technical data and recommended number of users supported'' of [[Howto:How to implement large PBXs#Technical data and recommended number of users supported|How to implement large PBXs]]) is factor 6 larger on the xx11 (1,536 GB) than on the xx10 (0,256 GB))
* the xx11 has gigabit Ethernet while the xx10 has 100Mbps Ethernet. The xx10 is therefore not well suited for Apps with larger network traffic, such as Recordings
* the CPU of the xx11 (although it runs on the same frequency) is roughly 20% faster than the xx10

While it is hard to predict the performance of the App Platform in a specific scenario, we see that in a real life environment an App Platform running on an xx11 platform can well support 150 users. The xx10 platform is estimated to support 120 users. Because CPU performance is the limiting factor, larger setups can be built based on the virtual machine platform (see [[#App services and multi-threading|App services and multi-threading]] below).

<references/>

= App Platform - x86-64 (Virtual Machine 64bit) =

* The default disk size is 16GB. It should be increased '''before''' the first start if needed!
* Multiple CPUs are supported, default is one CPU
* default RAM: 512MB
* static IP address, DNS, Gateway can be configured with the command '''setip''' on the console. Run '''setip --help''' to get a list of parameters. (Example: setip --addr=x.x.x.x --mask=x.x.x.x --gateway=x.x.x.x --dns1=x.x.x.x)
* If you have permission problems change to su user (Password is iplinux or your new admin password)
* To figure out your ip address you can use the command: ''ip address'' on the console.
* '''loadkeys de''' can be used to change to german keyboard layout (etc.)
* partitions<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 ext2: 350MB (contains ramdisk, rootfs and kernel)
*** the real partition format size is smaller but there is no need to monitor sda1 as sda1 won't grow during usage of the App Platform
*** sda1 is completely exchanged during an image update and its size might have changed but will never exceed these 350MB
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB
* VMWare Tools: Open VM Tools
* Qemu Guest Agent: installed since 110032
** The qemu guest agent can be configured in Proxmox with ''Virtio'' or ''ISA''. Before version 130012, you must use ISA, as Virtio was not supported with older versions.

<references/>

= Installation =
==ARM Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-armel.img'' image file.
* The installation runs without any further required step.

==ARM64 Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-arm64.img'' image file.
* The installation runs without any further required step.

==Virtual machine==

* Import the image into your server environment.
** Proxmox: follow this description here, just with the app-platform-ova.zip: https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Proxmox_VE
* Edit the disk size, if needed.
* Start the machine and wait until it reboots and starts again.
* Note: If you need to access an IP addresses available through a VPN connection from from inside the virtual machine, it could be that you need to set the network of your VM to NAT (and also add the URL for an IP to /etc/hosts)

[https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Configuration More Configuration Hints regarding VM Ware]

== Backup of the Apps ==

Each App Service can have multiple instances and each instance has its own database. The manager app itself also has its own database. 
There are no other files which need to be backuped. 
The standard way to backup the databases is through the Devices App [[{{NAMESPACE}}:Concept_App_Service_Devices#Backups]]. 
 
An alternate way is to use a command file which is similar to the command files from the firmware.

===Commands===
* '''times''' 0,12 # backup only at 0 or 12 o'clock
* '''backup-instances''' http://user:pw@ip/path/#I-#D.dump PUT
** PUT and POST are supported, all instances including the manager itself are saved
* '''backup-instance''' http://user:pw@ip/path/#I-#D.dump apidemo example.com PUT
** backup a single instance with instance name and instance domain
* '''backup-manager''' http://user:pw@ip/path/#I-#D.dump

===Hash parameters===
* #L App Platform label (neu), e.g. 10024
* #A App label (neu), e.g. 130004
* #I instance name (neu), e.g. reporting1
* #D instance domain (neu), e.g. innovaphone.com
* #m MAC address of the LAP, e.g. 00ab11eeff
* #d Current date and time (plain UTC without daylight saving and timezone adjustments) 20051010-170130
* #bn rolling backup index (n >=0 and <= 9, just one digit)
* ## escapes a hash mark

= App Platform Infrastructure and Concept =
== Webserver ==
The app platform includes a webserver that is highly optimized for handling many Websocket connections at a low memory footprint.
All apps use that webserver by registering for specific HTTP subpath. So they can all use the same HTTP/HTTPS ports - typically the standard ports.

=== Import Custom SSL Certificate ===
You have to upload a PEM Certificate with the following chain structure and without password encoding.

-----BEGIN CERTIFICATE-----
(certificate: eg. your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: eg. DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: eg. TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: eg. your_domain_name.key)
-----END RSA PRIVATE KEY-----

If you have problems generating the complete and correct certificate chain, you can use tools such as https://whatsmychaincert.com/ as an aid.
'''Please keep in mind that you never give away the private part of your key.'''

=== Known issues ===
*The app platform webserver can use only the default http/https ports 80/443.
*By design, there is no possibility to restore the default webserver certificate on the App Platform, if another certificate was once uploaded. 
**If nevertheless needed, you must login with Putty (see [[#How to retrieve files from the AP| Retrieve files]]) and execute these commands as root:
**''psql -d manager -c "DELETE FROM config WHERE name='webserverCertificate'"''
**''/etc/init.d/S92manager restart''
*The app platform webserver interprets URLs case-sensitive. In other words, <nowiki>http://<addr>/file.txt</nowiki> is not the same as <nowiki>http://<addr>/FILE.TXT</nowiki>

== Database ==
The app platform creates a database for each app instance with a given password. In the installer there will be used randomly generated passwords. You can set a new database password for every instance in the Application Platform.

The apps should store all data in that database. That makes sure that a consistent backup and restore of app instances can be done by the app platform manager.
In hosted scenarios, having separate databases for each instance also makes sure that the data of different customers are clearly separated and can easily be moved from one physical platform to another.

The default configuration decline database request from extern. If you need external access you can change the PGSQL configuration (as root) in the file ''/mnt/sda2/pgsql/pg_hba.conf''.
After editing pg_hba.conf, the database-service has to be restarted with the command <code>/etc/init.d/S50postgresql restart</code>
(Please think about it before you do it, because a better way is to create your own local app with local database access.)

You can find the official documentation for the pg_hba.conf here: https://www.postgresql.org/docs/14/auth-pg-hba-conf.html

Please note that you do this on your own responsibility, that it makes sense to create a backup of the original pg_hba.conf
and that you may break your database server if you do not know exactly what you do!

Sometimes the Apps are not proper working after this. You can wait a while until everything is working again or you go the hard way:
* stop the manager
** <code>/etc/init.d/S92manager stop</code>
* restart the database-service (maybe not really necessary, but makes a good feeling)
**<code>/etc/init.d/S50postgresql restart</code>
* start the manager
** <code>/etc/init.d/S92manager start</code>

=== Nightly database analyse ===

Every database is analysed at night to keep indexes in sync with the data. This triggers a ''vacuumdb -a -z'', which updates optimizer statistics, but does '''not''' shrink the physical size of the database. 
This must be done manually in the instance settings.

== App Platform Manager ==
The App Platform Manager is the central component of the App Platform. It does the following:
* Installing app services by downloading the binaries from an app store.
* Running and monitoring app services. If an app service crashes it is restarted, automatically.
* Management of app instances and providing them with the environment they need:
** A database
** A webserver path
** A password for authentication
* Backup and restore of app instances.
* Collecting debug information like tracing and crash dumps.
* System monitoring (CPU usage, memory usage, etc).

== App Services ==
App services are runned by the App Platform Manager. They implement an interface that is used by the manager to start, stop and configure app instances. Each service runs in a separate child process of the manager.

== App Instances ==
The actual functionality of an app service is provided by app instances. They run in the same process as the app service but have a distinct webserver path and their own database. There can be 0..n instances of an app service. Instances can optionally host (web) apps that can be opened in the myApps client.

Each instance of an App service has two passwords. The instance password itself and a database password. If you want to change it you must update the password on both sides. 
The instance password must match to the password in the corresponding PBX App objects, while one instance can have different App objects. 
The database password must be just known to the manager and not outside of the App Platform.

The ''Database name'' and ''Database user'' are both limited to a length of 63 characters. By default, the App Manager would create ''<domain>''_''<instance-name>'' as value for both. This is why it is recommended to use instance names so that length(name) + length(domain) is less than 63 characters. However, if this is not possible, you can manually shorten the suggested values (both must still be unique on your App Platform).

=== Cleanup database ===
You can cleanup the instance database inside the instance settings. This starts the vacuumdb process for the instance database which frees disk space of deleted rows.
Note that this process locks the database and that sufficient disk space is needed to complete it!

=== External database host ===
You can optionally configure an external database host, if the database shall be hosted on an external host. 
Note that the App Platform Manager still creates a local database, which is then not used as long as the external host is configured.

What are external databases useful for?:
* User data is too large (files are stored as BLOB in the database)
* Other (non-innovaphone) database servers are to be used due to other regulations
* There is already an external database cluster with its own backup/restore processes which should be used
* More performance is required (please note that a local UNIX socket provides much faster results than a remote database server). Depending on the app and the task of the app, it can still be useful to use a separate server if it is faster.

==== Supported database types ====
In principle, ''PostgreSQL'' and ''MySQL'' are supported. However, please note that the respective app must be designed for the target database server type. If an app has been developed for PostgreSQL, it cannot be operated on a MySQL server.

'''Please note:''' All innovaphone apps are developed exclusively as PostgreSQL apps.

MySQL therefore only makes sense if own apps are developed and MySQL or certain MySQL features are to be used. For such apps, it is very important to deactivate the automatic Application Platform APP-Backup.
The database backup process of the App Platform uses PostgreSQL backup commands, which is why the backup would fail, so the app must be excluded from the backup, and you must take care of the backup yourself.

==== Database creation ====
If you use an external database, you have to create the database itself.
The App Platform Manager itself creates a PostgreSQL database like this (you may respect this on your database host to be compatible with the database implementation inside the Apps):
* CREATE DATABASE "dbname" ENCODING 'UTF8';
* CREATE USER "dbuser";
* ALTER USER "dbuser" WITH PASSWORD 'dbpassword';
* GRANT ALL PRIVILEGES ON DATABASE "dbname" TO "dbuser";
* ALTER DATABASE "dbname" OWNER TO "dbuser";
* REVOKE CONNECT ON DATABASE "dbname" FROM public;

==== Database connection ====
There are different possibilities to specify the host. You can use a DNS-Name, IPv4 or IPv6. A port can be optionally added with a colon.

Our PostgreSQL implementation sets sslmode=prefer, so SSL is used by default if enabled on the server.

==== Backup/Restore ====
External databases are still backuped as normal, but you can't restore such a database with the App Platform Manager on the external host! You must restore such a dump manually on your database host.

==== Database redundancy ====
In principle, it is possible to create redundancies for failure scenarios through this function.

However, there are different scenarios that need to be evaluated on a case-by-case basis:

* One database, multiple App Platforms (primary online / secondary '''offline''') where multiple apps access the same database.
** This mode of operation is legal as long as you can really ensure that only one App Platform is active at a time.

* One database, multiple App Platforms (primary online / secondary '''online''') with multiple apps accessing the same database.
** This operating mode cannot be used for innovaphone apps, as the app itself would have to be developed for such a mode, which it is not.

However, we advise great caution here! The use of the same databases from different nodes may only be used if you can ensure that the databases or runtime environments of apps cannot get into a ''split-brain'' mode.

== Relationship between app instances and app objects in the PBX ==
Typically an app instance is connected to one or more app objects in a customer PBX. This is done by configuring the same parameters on both sides:
* URL
* Password
The password is used by the PBX for authenticating itself, users and services against the app instance.

Some apps need a websocket connection with the PBX. When "websocket" is activated at the app object, the PBX establishes a websocket connection to the app instance and provides the APIs that are configured at the app object.

=== Supported scenarios ===
It is important to understand that the concept does not do any assumptions on how PBXes and APs are correlated. So you can have
* One App Platform for one customer
* One App Platform for many customers
* Many App Platforms for one customer
* Many App Platforms for many customers

Attention: The V13 installer can only configure the scenario "''One App Platform for one customer''". If you want to have a different scenario, you have to configure it manually.

For hosting or cloud scenarios you need special scenarios. Please refer our [[Howto:V13 Hosting| V13 Hosting]] instructions.

=== Restrictions ===
Currently we don't have redundancy for app instances or App Platforms.

== Update of the App Platform itself ==
The App Platform is build on top of buildroot and will receive updates and fixes from time to time. 
You can update the used build inside the Manager App by using the '''Update''' button at the top. 

It is strongly advised to make a full backup (VM) or at least backup all apps (Gateway) before you run such an update!

After the update has been downloaded and verified, your App Platform will reboot.
You can check the installation process after the reboot with the following URL: https://IP-of-AP/manager/ramdisk.log

== App services and multi-threading ==
Each App Service runs in a single process with no multi-threading, independent of the instances of the App Service. However, each instance maintains its own database connection and the database responds to this connect with the creation of a new process. Each app service therefore uses 1+''n'' threads (where ''n'' is the number of instances). All communication between app service instances and their clients must pass the single-threaded web server. On platforms with multi-threading support (i.e. VMware or Hyper-V), up to 1 + ''m'' + ''m'' * ''n'' (with ''m'' being the number of Apps and ''n'' the number of instances per App) threads can be utilized.

= AP Manager settings =

== General ==
* ''Enable Developer mode'': in developer mode, apps can be manually uploaded without an App Store
* ''Disable App security'': each App has an own unix user and if this flag is set, the user can login with SSH for debugging
* ''App Store URL'': the URL to the App Store where Apps are searched and also an update of the AP image itself
* ''Devices app URL'': the URL to the Devices App to manage the AP through Devices
* ''Devices app URL 2'': don't use!
* ''App Platform DNS name'': currently not used
* ''NTP server 1/2'': NTP servers for this AP (in addition to NTP servers retrieved by DHCP)
* ''Timezone string'': A timezone string which is used by the App Platform Manager to do certain jobs according to the configured timezone.
** Note that this doesn't change the timezone of the linux itself!
* ''DNS server 1/2'': DNS servers for this AP (in addition to DNS servers retrieved by DHCP)
* ''Database optimization time'': The database optimization process will be started at this hour (local time), with a random offset of up to 7 hours
* ''Command file'': obsolete, use the Devices App for backups!

== Security ==
* ''Current Webserver certificates'': shows the current certificates with the ability to download them.
* ''Webserver certificate'': upload a webserver certificate in PEM format
* ''AP Manager password'': the password to the web interface of the AP Manager (normally set through Devices)
* ''Linux root user'': password of the root user (normally set through Devices)
* ''Linux admin user'': password of the admin user (normally set through Devices)

== Let's Encrypt ==

Configure the certificate creation by Let's Encrypt here.

* ''Enable'': turns the automatic creation on or off
* ''Let's Encrypt App URL'': the URL of your Connector for Let's Encrypt App Service. You can copy&paste this URL from your Connector for Let's Encrypt PBX Manager Plugin
* ''Let's Encrypt App Password'': the client password of your Connector for Let's Encrypt App Service. You can copy&paste this password from your Connector for Let's Encrypt PBX Manager Plugin
* ''Key length'': 2048, 3072 or 4096 (keep in mind, that [[{{NAMESPACE}}:Certificate_management#Certificate_Key_Length_and_CPU_Usage|a higher value provides higher security but also lower performance!]])
* ''DNS Name'': the external DNS names of your device (up to 100 possible)

== Alarms and events ==
* ''URL'': URL to the Events app
* ''Username/Password'': HTTP credentials of the Events app
* ''Email address'': an email address which will get emails on full disk alarms/warnings
* ''Threshold'': All Apps will be stopped and an hourly email sent on reaching this threshold. An alarm is generated 10% before reaching this threshold and an email is sent every 24 hours.

== SMTP ==
SMTP server settings for sending emails from within the AP Manager.

== Replication ==
App Platform [[#App Platform replication|replication settings]]

== Registered Access Domains ==

== Update ==
Updates the App Platform to the latest image available on the App Store.

== Restart ==
Restarts the App Platform.

== Shutdown ==
Shuts down the App Platform.

= App Platform replication =

== Requirements ==

* 13r3 or above on both standby servers and the primary server
* at least an App Platform image starting with version 110002 (otherwise postgresql is too old)
* standby and primary servers must have the same system architecture
** arm gateways (IPx11) just with arm gateways (IPx11)
** arm64 gateways (IPx13) just with arm64 gateways (IPx13)
** x86_64 virtual machines just with x86_64 virtual machines
* the disk size on standby servers must be at least equal as the disk size on the primary server

== General ==
The configuration is done within the App Platform Manager next to the settings button under "Replication".

=== Off ===
No replication is done at all.

=== Primary ===
The App Platform acts as primary server for one or multiple standby servers. 
Max 8 standby servers can be configured. 
 
Every standby server must get a unique name on the primary server which is then also configured on the standby server itself. This is due to the fact, that the primary server preserves data for every standby server while it's not reachable. 
A standby server name must be a valid domain name, although this name is currently not used as DNS name (but might be used in the future). 
 
The password is randomly pregenerated and must be used as handed by the App Platform Manager.

==== PostgreSQL port ====
The default PostgreSQL port is 5432 and can't be changed on the primary. It must be reachable through your firewall or at least forwarded on a different port towards this App Platform on port 5432.

=== Standby ===
Configure the password from the primary and one of the not yet used standby server names. 
The host and port must be reachable through the network. You can specify a non default port which then must be forwarded somewhere else to port 5432 on your primary.

*Note: Do '''not''' configure the same standby name on different standby servers, as this will break the replication on at least one standby! 
*Note: On a standby, all '''locally installed apps are removed''' during installation

== Failure detection ==

The replication state on both primary and standby servers are continuously monitored. 
In case of a broken connection, an alarm is triggered at once and just cleared if the failure goes away. 
 
If such an alarm lasts for 5 minutes an email is send. The recipient address must be configured in the App Platform Manager settings under "Alarms and Events" and you must also provide a valid SMTP configuration.

== Failover ==

There is no automatic failover procedure. If you detect the failure state, you must get active yourself.

=== Standby down ===

Fix the standby server and see if the replication comes up again. If not, setup a new standby server which will replicate the whole database cluster from scratch.

=== Primary down ===

If the primary is down and cannot be brought into life again, you must take the following steps, depending on your configuration:

==== One standby server ====

* Disable the replication in the replication configuration. You will then have a standalone App Platform afterwards.

==== Multiple standby servers ====

* Change the replication type on one of the standby servers from standby to primary. Please note that the other standby entries must still exist here (they are automatically offered)!
* Change the host entry on the other standby servers to the new standby server. The standby server will sync the whole database cluster again, which will take time.

==== Configuration changes ====

You must also tell the PBXes and other tools to use the new primary server.

* You may simply change the IP address behind the DNS of your primary server to point to the new primary server.
**Note: to ensure rapid recognition of the new DNS target, the definition of an appropriate TTL value is recommended
* Without DNS, you must currently modify the configuration by replacing the IP address of the old primary with the new address.
** This must be done in every master PBX configuration.
** This must be done in every App configuration which may use this IP address, e.g. Devices which rolls out an alarm server configuration

== App Platfom update ==

If you're running an active standby server and the major version of the PostgreSQL database didn't change, you can simply update primary and standby servers independently. 
 
If it contains a ''new major version'' of the PostgreSQL database, you must follow these steps:

* deactivate replication on all standby servers (which promotes these standby servers to active servers)
* ensure that the '''same''' App Platform Manager version is running on primary and standby servers!
* perform the App Platform update on the primary server
* perform the App Platform update on the standby servers
* reactivate replication on the standby servers (which will do a full replication again, so it might take some time)

Alternativly you may setup the standby server from scratch directly with the new App Platform image version.

Sadly there is currently no better method offered by PostgreSQL to perform such an upgrade.

See also https://wiki.innovaphone.com/index.php?title=Howto14r2:Firmware_Upgrade_V14r1_V14r2#App_Platform_and_Apps

== Technical backgrounds ==

=== Streaming replication ===

We use the asynchronous [https://www.postgresql.org/docs/9.3/warm-standby.html#STREAMING-REPLICATION streaming replication of PostgreSQL]. A transaction thus just waits for a commit on the primary server. Standby servers will receive the transaction asynchronously afterwards to avoid a reduced writing performance. 
A primary server keeps the neccessary WAL files for every standby server until the standby fetched the neccessary information. 
This fact can lead to higher disk space usage on the primary if one or multiple standby servers are offline for a while.

Take care to fix broken replications as soon as possible to avoid a full disk on the primary server!

=== What is replicated ===
The whole database cluster of an app platform is replicated. This includes every database of every instance and the database of the App Platform Manager itself. 

=== App Services on standbys ===
The database of the App Platform Manager itself also contains the App service binaries to be able to restore applications in a failover case. 
You do not have to install App services on the standby if you install them on the primary. 
App Platform Manager and Webserver can be updated as usual through the App Store or the Devices App if the standby is connected to Devices.

=== App Platform Manager configuration of the standby server ===
The App Platform Manager configuration of the standby server cannot be stored inside the database, as the database is readonly. So it is stored inside a configuration JSON file under ''/home/root/standby.conf''. 
This configuration is backed up as usual by a Devices backup job and can be also manually restored on a standby (not on a primary though!).

Configuration options from the primary are not synced to the standby server, as the standby server has its own configuration (as it could be in a different network etc.)!

=== No automatic failover ===

There is currently no automatic failover mechanism. PostgreSQL doesn't offer multi master replication, so writing is just possible on the primary itself. Standby servers have a readonly database. 
Let's consider the following use case if we would implement an automatic failover with the current technical possibilities: 
* The primary server is connected to a master PBX.
* A slave PBX is also connected to the primary server in another location.
* A standby server is in this location and replicates from the primary.
* The internet connection between primary and standby fails.
* The standby promotes itself to primary, so that the master PBX now writes to the old primary and the slave PBX now writes to the "new" primary.
* The internet connection comes up again and both primary and standby servers now have databases which are out of sync and which cannot be merged.

=== Security ===

* port 5432 must be reachable on the App Platform
* For every standby a PostgreSQL user is created with the REPLICATION role on the primary. Just this user has access to the database server from non localhost connections.
* You cannot establish a standard connection with such a user and modify/read from tables.
* The replication connection is established over TLS by default.

= App Installer PBX Manager Plugin =
== Requirements ==

* V14 and above

== General ==

The app installer plugin allows IT administrator (with access to the PBX Manager) to install/update/delete new apps from the innovaphone app store including Partners apps. It is automatically available with existing app platforms or after adding a new one in the PBX Manager.
It offers a view to the App Platform Manager‘s App Store with all the available functionalities and simplifies the install, update and uninstall of apps.

== Dedicated AP for each user ==

Installing a new app will install the app service and add a new instance with the user’s domain. The instance is automatically started. 
This further enables the configuration of the instance through its respective PBX Manager plugin. 
Uninstalling the app will remove the app service and the corresponding instance.

== Shared AP between users ==

Installing a new app works in a similar way to that of the dedicated AP. However, each time a new user installs the app, only a new instance is created if the app service is already installed. 
A user can uninstall the app, in this case the corresponding instance is deleted. If no more instances exist, then the app service is uninstalled. 
The administrator can only update the app service in such scenario.

= Known Issues =

== Reboot after an image update hangs (ARM gateway) ==

If it happens, that the App Platform doesn't recover after the reboot, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
If '''Kernel command line''' is set to '''/dev/ram0''', the App Platform booted the ramdisk. 
 
Try to fetch the upgrade log file:
https://[APP-PLATFROM-IP/DNS]/manager/ramdisk.log
 
If this doesn't work, try to login with putty in this case (default credentials admin/ipapps and root/iplinux) and issue this command: 
''cat /apps/install_step1.log'' 
 
If this file contains '''finished''' at the end, you can reconfigure the settings under App Platform -> General: 
* press '''Stop'''
* Initrd file: empty
* Kernel command line: '''root=/dev/sda3'''
* Ramdisk size: empty
* press '''Start'''

The App Platform should boot and run the already updated image.

<pre style="color: red; font-size:150%;">---WARNING---
If the file doesn't contain "finished" at the end, you may still need to wait, as an upgrade may take some time!
Do not reconfigure without being sure that the upgrade has finished, otherwise your system may won't run!</pre>

== Reboot after an image update boots always into rescue mode (virtual machine) ==

This most likely means that the image installation didn't finish the first time and was interrupted before the bootloader settings could be changed back to the default partition. 
 
If your App Platform doesn't boot or isn't normally accessible after manual selection of the standard entry in the boot menu, you need to '''revert''' to a '''snapshot/backup''' prior to the update. 
If your App Platform runs normally though, you can follow this instruction to change the default boot entry: 
 
* boot into the '''rescue''' partition
* login with root/iplinux
* edit the file /boot/grub/grub.cfg
** search the line with '''set default=0''' and change it to '''set default=1'''
** reboot

== App Platform doesn't start after an update ==

=== Gateway ===
If it happens, that the App Platform doesn't want to start an update, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
* '''Shutdown''' the App Platform and '''Stop''' it 
* Set '''Kernel command line''' to '''/dev/ram0''' 
* Set '''Initrd file''' to '''ramdisk.ext2.xz''' 
* Set '''Ramdisk size''' to '''100000''' 
* '''Start''' the App Platform now. 

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

Note: This process can take a while, after it's finished it reboots and automatically change the '''Kernel command line''' value.

=== Virtual Machine ===

Boot into the '''rescue''' partition.

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

=== It still doesn't start ===

If it still doesn't start, configure the App Platform to boot from /dev/sda3 (or inside a VM start the second boot loader entry) and login with SSH as root.
Then do a first check to verify that you have a specific error due to an incomplete update or a [[Howto15r1:Firmware Upgrade V14r2 V15r1#AP Upgrade to Image 130006|wrong update order]]:

* /etc/init.d/S92manager stop
* /apps/manager/manager
* if this outputs '''error while loading shared libraries: libcrypto.so.3:''' you have a manager version which cannot run on the current image.

In this case you must download an older build (14r1 1410593):

* /etc/init.d/S92manager stop
* wget --no-check-certificate -O /apps/manager/manager https://webbuild.innovaphone.com/1410593/arm/manager/manager
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* wget --no-check-certificate -O /apps/webserver/webserver https://webbuild.innovaphone.com/1410593/arm/webserver/webserver
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* chown root:root /apps/manager/manager
* chown root:root /apps/webserver/webserver
* chmod +x /apps/manager/manager
* chmod +x /apps/webserver/webserver
* echo 110000 > /mnt/sda1/label
** this allows the manager to perform an image update again
* /etc/init.d/S92manager start
* now perform an image update and '''afterwards''' update your apps again

== Webserver doesn't respond after an image update ==

If you can't reach the web UI after an image update, please try to connect with SSH as admin user and delete old coredumps, which may prevent the App Platform Manager from starting correctly:
* su root (become root)
* rm -f /mnt/sda2/log/core_dumps/*/*
* /etc/init.d/S92manager restart

Check if you can now reach the App Platform again.

= Tracing =
Each App Service has its own log file, which can be accessed through the Manager App. You can configure a log file size for each App Service. 
Each App Intance has its own trace flags. The following trace flags can be set: 

* Alarm client: used by the manager to send alarms to an alarm server
* App: logs from the App Service itself
* App WebSocket: logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
* AppSharing: just native clients
* AppProxy: just native clients, logs requests which are proxied between the local webserver and the remote server
* Audio: just native clients
* Browser: just native clients
* Command: the command interface is used to execute shell commands, e.g. used by the manager App
* Config: logs config changes of an App
* Database: database logs
* DB files: database file logs
* DNS: DNS request logging
* DTLS: just native clients, DTLS request logging
* Ethernet: interface to get ethernet adapater infos, just manager App
* File: logs for file system access (synchronous), e.g. manager App
* Files: logs for file system access (asynchronous)
* HTTP client: http client logs
* HTTP file: logs for static HTTP files
* ICE: just native clients
* LDS: local domain sockets
* Media: just native clients
* Media channel: just native clients
* Process: IProcess interface logs which is used for spawning, killing processes etc.
* SMTP: SMTP client logs
* TCP: TCP logs
* Time: ITime interface logs
* TLS: TLS logs
* TURN: just native clients
* UDP: UDP logs
* Video: just native clients
* WebSocket client: logs outgoing websocket connections
* Webserver traffic: logs incoming HTTP traffic, which is forwarded from the webserver to the App
* WebDAV service: logs WebDAV requests to the App
* Webserver: enables webserver specific logs

== RPCAP ==

If you open the Manager App, click on the Manager in the left list and then on the Diagnostics button, you can enable RPCAP. 
You can add the interface in wireshark with the string:
rpcap://<APP-Platform-IP>/eth0

'''Please don't forget to disable RPCAP after your testing!'''

= How-Tos =

== How to retrieve files from the App Platform ==
To retrieve files from the App Platform which can not be retrieved via the App Platform manager UI, you can connect to the App Platform using the SCP protocol on port 22. 
 
First copy files to /home/admin as root with Putty or another SSH client:
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''su root'' to be root (''iplinux'' as default password)
 
You can now copy files to ''/home/admin'' (e.g. from /var/log/apps/manager/...). 
 
You can create a tar archive with all logs like this:
* cd /home/admin
* tar -cf - /var/log/* | xz -z - > log.tar.xz
** you may want to exclude coredumps (due to their size):
** tar -cf - --exclude=/var/log/core_dumps/* /var/log/* | xz -z - > log.tar.xz
* chown admin:admin /home/admin/log.tar.xz
 
Then copy the files to your local system, e.g. with WinSCP 
* use ''SCP'' as protocol (NB: WebDAV is not supported on most of the directories on the App Platform )
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''/home/admin'' as start directory
* copy the needed files

== App Platform disk space warning ==

If the configured threshold is reached, all Apps are stopped inside the App Platform . You must then free disk space somehow.

=== Find large instances ===
Click through your apps in the tree on the left side and take a look at the database size of each instance.

=== Delete data inside an instance ===
It depends on the type of app if you can delete data or not. E.g. you can start the Files app and delete files inside this app. 
This won't reclaim disk space though due to the way how PostgreSQL databases work, so you need to follow this guide to reclaim the disk space:

* start the corresponding App
* delete data inside the App
* optimize disk usage of the database by cliking on the button "Clean up database" under Edit instance. If this does not help, continue with the following steps.
* stop the corresponding App again
* download a backup of the instance (backup button at the top), this backup contains the whole instance data, also the password of the instance
* delete this specific instance
* restore the downloaded backup (restore button at the top)

Depending on the hardware and the size of the instance, this process may take hours to complete!

=== Resize the disk ===
The resizing of a disk is just possible for virtual machines, see [[#Resizing the disk of a Virtual machine|Resizing the disk of a Virtual machine]].

=== Delete the whole instance ===
If there is no other possibility, you can delete the whole instance. Afterwards you recreate the instance with the same values and a new random password. Don't forget to set this password in the corresponding PBX App objects though!

=== Restart the Apps or the App Platform ===
If you have enough disk space again, you must either restart the whole App Platform or you manually start all Apps again.

== App Platform/Apps app not online anymore due to full disk ==
If the apps app is not online anymore and you can't access any apps anymore, try to login with an SSH client to see if your disk is full.
Login as admin and afterwards as root (su root). 
 
* issue '''df -h''' and see the disk usage of /dev/sda2, if this is 100%, your disk is too full
* stop the manager
** /etc/init.d/S92manager stop
* empty the 500 MB file, which is exactly for this case here (manager must be 13r1 SR9 or higher to have this file)
** echo "" > /mnt/sda2/empty_if_no_space
* delete log files to recover some space
** rm /var/log/apps/*/*
** rm /var/log/core_dumps/*/*
* restart the postgresql server (see the output if this worked or not)
** /etc/init.d/S50postgresql restart
* restart the manager
** /etc/init.d/S92manager restart
* wait until everything is online again
* open the Apps app and try to find the instance which uses the most disk space and try to delete files/content from it
** you may want to stop all app services first to prevent more writes to the database
** if not possible, you can delete this instance, but you'll loose all data from this instance then!
* after that you can try [[{{NAMESPACE}}:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files|Reference14r2:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files]] to free up space
** If this does not work you can create a backup from the database, delete the database and import the database again.
* free up at least 500 MB so that the manager can create the file again
* delete /mnt/sda2/empty_if_no_space if you are done and restart the manager:
** rm /mnt/sda2/empty_if_no_space
** /etc/init.d/S92manager restart
** the manager restart automatically recreates the empty_if_no_space file if this file doesn't exist

Make sure, that you do '''not''' have backups configured to a local files instance while this files instance is not excluded from backups.
An instance can be excluded from backups in the instance settings in the App Platform Manager.

If all of this doesn't help, you can resize the file system on a VM:
* proceed with [[{{NAMESPACE}}:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine|Reference14r2:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine]]

== Resizing the disk of a Virtual machine ==

Do '''NOT''' resize if you're running an App Platform version higher than '''110000''' and lower than '''110027''' or '''130007''' and lower than '''130015''' or your data will be lost!
Please update your App Platform to version 130015 or higher before you start resizing your disk.

* stop the VM
* expand the disk using your VM utilities
* start the VM and boot from the first boot entry '''rescue/setup'''
* login with '''root''' and '''iplinux'''
* execute this command: '''/home/root/install_step1.sh log.txt resize'''
* the VM reboots automatically after a successful resize

== Shrink the physically size of PostgreSQL database files ==
Tuples that are deleted in your database are not physically removed from the database-file. So the claimed space on the harddisk is still in use after the delete operation.
If you need to free up some disk space you can force to reorganize the physically database-file on your harddisk.

You can also start this process through the instance settings as long as the App Platform Manager is still running.

'''Important: You are operating on the Database, you have to make a Backup of your Database before you do this!'''

Login via SSH to the APPlatform with the ''admin'' User
su root

=== All databases ===
/etc/init.d/S92manager stop # not always needed, but in case of database errors recommended, of course no app is online then
sudo -u postgres reindexdb -a
sudo -u postgres vacuumdb -a -f
/etc/init.d/S92manager restart # just execute if the manager has been stopped above

=== single database ===
sudo -u postgres reindexdb -d dbname # for a single database with dbname
sudo -u postgres vacuumdb -d dbname -f # for a single database with dbname

Note: This may take some time and the App database is not available during this time

After the process you can check the free dispace via <code>df -h</code>. You can check the claimed space from the database file with the command <code>du -sh /mnt/sda2/pgsql/</code>.

== Change IP Addresses / DNS Names / System Name ==

If you want to change the System Name or the DNS Name of the PBX and/or App Platform Platform you must change records manually '''in the described order'''!
You have to know the Admin password to directly Login to the App Platform .

=== App Platform ===
; Settings - General
* ''Devices app URL''
* ''App platform DNS name''

; Settings - Alarms and Events
* ''URL''

; All Instances
* ''Domain''
* ''Webserver path''

=== PBX ===
Download the configuration and ''search/replace'' in the config file. Upload the config file and reboot.

Manual:
* ''URL'' in all PBX Object (Apps, Voicemail ...)
* [[{{NAMESPACE}}:Gateway/CDR|CDRx]]
* [[{{NAMESPACE}}:PBX/Config/General|IP address for App Platform]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reset Password Page]]
* [[{{NAMESPACE}}:PBX/Config/Authentication|Verification link]]

Depending on your change you have to activate/deactivate the Setting [[{{NAMESPACE}}:PBX/Config/General|Operation without DNS]]

=== Additional Devices / Steps ===
* ''Devices Registration URL''
** There is no automatism to change the URL on all devices in your setup.
** If you have the option to use DHCP, you can temporarily overwrite the [[{{NAMESPACE}}:Services/Update|Update URL]] and execute a [[{{NAMESPACE}}:Concept_Update_Server|custom update script]] to change the ''Device Registration URL''
* ''Alarm server''
* Reverse Proxy configuration
* Change ''Domain Name'' in Devices if you have also changed the system name

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

initial error at 1500329378: ext4_journal_start_sb:328
last error at 1500329378: ext4_journal_start_sb:328

Or you get events like "Broken file system" from your App Platform .

This indicates a file system failure on the Linux Installation.

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

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

=== Gateway ===

* Open the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the Kernel command line from root=/dev/sda3 to root=/dev/ram0
** modify the Initrd file to ramdisk.ext2.xz
** modify the ramdisk size to 100000
** start Linux again
:: This will run Linux on another (hopefully sane) partition.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system

* go back to the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/ram0'' to <code>root=/dev/sda3</code>
** clear the Initrd file field
** clear the ramdisk size field
** start Linux again
:: This will run Linux on the original partition.

=== VM ===

Restart the VM and select the first entry in the boot menu from grub.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system
* Reboot your VM
[[Category:Concept]]

== How to create a memory dump of a running process ==

Sometimes it's usefull to have a memory dump of a running process to investigate certain issues.

* login with SSH and become root
* find out the PID of the relevant process, e.g. with ''ps aux | grep /apps/manager/manager | grep -v grep''
* gdb --pid PID -ex gcore --batch
* this creates a core file core.PID
* download this core file with WinSCP or similar tools

== Move instance database to external database host ==

In case you want to use an external database server instead of the integrated:

* download a backup of the specific instance over the App Platform Manager
* create a postgresql database on the external host:
** createdb --encoding=UTF-8 exampledb
* restore the backup
** pg_restore -d exampledb backup-exampledb.dump
* change the ownership to a specific postgresql user (which you have to create yourself first)
** psql -d postgres -c "ALTER DATABASE exampledb OWNER TO exampleuser"
* configure the database host, name, user and password on the instance inside the App Platform Manager

Reference:My Innovaphone

2025-08-11T05:20:30Z

Dde: /* Download App development license */

==Where is my old my.innovaphone?==
Don't worry, just login with your old my.innovaphone account! You will be asked to confirm your forename and surname (just a '''natural person''' is allowed) and accept some terms and conditions. 
Afterwards you find the old license/device view inside the [[#Licenses tab| Licenses tab]].

==About==
my.innovaphone allows the handling of licenses and includes the handling of device warranty and software service agreements. 
You can also sign contracts here for different purposes.

===Project-View===
My innovaphone offers the possibility for several users to be in one company. This company shares its balance of licenses over all users and can have several projects. Projects have their own balance of license types and devices are bound to a project.

===Language===
My innovaphone will support multiple languages. You can select your desired language at the top of the page. 
Currently supported languages:
* English
* German
* Italian
* Dutch
* French
* Spanish (partially)
* Polish (partially)

===Guides===

====Quickstart guide====
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_nl.pdf Dutch quickstart guide] 
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_en.pdf English quickstart guide] 
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_fr.pdf French quickstart guide] 
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_de.pdf German quickstart guide] 
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_it.pdf Italian quickstart guide] 

====SSA guide====
;V10 and greater:
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10nl.pdf Dutch SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10en.pdf English SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10fr.pdf French SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10de.pdf German SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10it.pdf Italian SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10pl.pdf Polish SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10es.pdf Spanish SSA guide] 

;V8 and greater:
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_en.pdf English SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_fr.pdf French SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_de.pdf German SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_it.pdf Italian SSA guide] 

==First steps==
Open [https://my.innovaphone.com my.innovaphone.com] and click the "I would like to create a new personal user account" link.
Enter your personal data and register.

You will receive a registration email with an activation link.
After account activation you have two options:
* create a new my.innovaphone company with the "Create company account" button
* ask another user of your company to invite your email address to an already existing company

If you accidentally created an own my innovaphone company, just ask another user of your company to import your just created company.

If you create a new company, you can '''optionally''' enter your innovaphone account ID (which is your customer number with innovaphone) with your postal code, to retrieve your company data.

Inside the license tab of the my.innovaphone portal, you will see a help link at the right side of the horizontal tab menu.
This link shows the corresponding text of the wiki section, when hovering with the mouse over it,
and redirects to the corresponding wiki menu, if clicked.

It is possible, that one user is member of serveral companies!

==Left bar==
If you open the left bar, you have the options to:
* select one of your companies
* edit your personal user account
** user name
** email address
** flag to recieve SSA expiry emails
** password
* create a new company
[[Image:Myinnovaphone bar.png|center|thumb|200px|myinnovaphone_bar.png/|myinnovaphone_bar.png/]]

==Main tabs==
Inside each company you see the three main tabs:
* Contracts
* Authorized persons
* Licenses (see [[#Licenses tab| Licenses tab]])

You may also have two buttons:
* Add Contract (just as company administrator or with the contract right)
* Invite person (just as company administrator)

[[Image:Myinnovaphone main.png|center|thumb|200px|myinnovaphone_main.png/|myinnovaphone_main.png/]]

=== Contracts ===
Inside the contracts tab, you see all your contracts and you can download these conracts. 
In general, contracts must be first approved by innovaphone, so you see three types of contracts:

* open contracts which must be approved by innovaphone first
* approved contracts which can be already used
* cancelled contracts which are not valid anymore

[[Image:Myinnovaphone contracts.png|center|thumb|200px|myinnovaphone_contracts.png/|myinnovaphone_contracts.png/]]

These type of contracts currently exist:
==== innovaphone myApps Cloud Service ====
Conclude this contract to use the innovaphone myApps Cloud.

==== innovaphone software rental ====
Conclude this contract to rent innovaphone software products. You must conclude this contract if you want to use the software rental inside the Devices App.

=== Authorized persons ===
Here you see all persons which exist inside your company. Each person can have the following rights:
* Administrator (everything)
* Contracts (can conclude contracts)
* Licenses (can work with licenses)
* Viewer (can just see everything without doing something)
* Locked (cannot even login to this company anymore)

=== Licenses ===
Here comes the old my.innovaphone view which allows the handling of devices, licenses, activation keys etc.

==Search (inside licenses tab)==
At the right top of the licenses tab you have a search field. You can search for different things:
* Devices (part of a device name or device comment)
* Projects (part of a project name or project description)
* Own activation keys (part of an activation key or its description)
* Hardware rental orders (part of the innovaphone order number or your own order reference or a MAC address of an order)

You have to enter at least '''three''' chars to start a search. To search for activation keys,
you have to enter at least '''five''' chars.
* Search for license types. Enter e.g. "PBX-Port8" to find all devices with Port8 licenses or enter "PBX-Port8=100" to find all devices with Port8 licenses '''>=''' 100.
* Search for products, e.g. 01-00811 für IP811 (such a search may take longer!)

==Licenses tab==
===Projects===
After creation of an own company, you will have a default project named "DEFAULT". You can rename this project later.
You can also create more projects on the projects page with "Create".
Each project of a company must have a unique name.

Do '''not''' set SSA, if you want to import your devices from your old license manager account first.
If you want SSA and you '''won't import''' devices into this project from your old account, you should set SSA at once.

You can select a certain project by activating it in the project list. This selection is then true for all other pages, as some pages require a selected project.

[[Image:overview.jpg|center|thumb|200px|overview.jpg/|overview.jpg/]]

By activating a project by clicking on the project name in the project list, you can manage this project and its settings.

==== Rental project ====
You can also manually create a rental project. A rental project is normally created automatically by uploading an activation key inside the Devices App. 
But if you want to start directly with an Automatic iSC reloading service, you'll need to create the project manually. 
Take care that the name '''equals''' the domain name in your Devices App. 
 
If the rental tab in your Devices App domain doesn't show the expected balance/Automatic iSC reloading contract/licenses etc., you may use the Devices App Guid Link mechanism to link the domain to this specific project (see below) (use Devices App '''13r3 SR12''' or higher!).

====Properties====
Rename the project or/and change its description. 
 
You can configure further CC mail addresses inside your '''License Purchase''' project, if you have one. If you purchase licenses on credit, the emails will be also sent to theses addresses.
 
 
Since version 10, an innovaphone device will automatically connect to http://config.innovaphone.com/init
This script looks at the project properties of the project, where the device exists. 
You can configure an update '''URL''' and a '''trusted certificate'''. 
 
;Devices App GUID link: This is a GUID which can be entered in the settings of a domain inside the Devices App to link the domain to this specific project, if the names do not match and/or the Devices App has been setup from scratch. The Devices App must use the customer to which this projects belongs to be able to use this GUID.

====Software Service====
You can put your project under SSA (software service agreement).
You will be asked to enter a SSA end date. This will be the date, where all SSA licenses of all devices in this project will expire.
The end date mustn't be more than one year in the past. 
Optionally you can enter a maximum SSC amount. The SSA end date will be automatically calculated then. 
If you have entered a maximum SSC amount, you have to use the '''Recalculate''' link to calculate a new SSA end date,
if you change your license selection.
 
You can also calculate SSA over all projects at once. In this mode, you '''won't be able''' to confirm the calculation. You'll just see the necessary SSC amount.

After entering a date/SSC amount, you will get a summary of all licenses, which will be put under SSA and the amount of needed SSC licenses.
The SSC value for each license is calculated by the bind date of the license and the entered SSA end date/SSC amount.

[[Image:Ssa_extend.jpg|center|thumb|200px|ssa_extend.jpg/|ssa_extend.jpg/]]

If you have licenses for an older version than the current version, you have to pay SSCs from the [[#Release dates|release date]] of the next version of the current license version. 

e.g. you have a V7 PBX-PBX7#15 license with bind date 1/1/2010. Version 8 was released on 7/12/2009, so SSA is
calculated from 7/12/2009 for this license. You will see the calculation date in the list under "bind date"

If licenses already have a SSA date, just the difference between the current SSA date and the entered SSA end date must be paid.
If the bind date of the device lies in the past, the difference between the bind date and the current date must be paided twice (this is the column 'days*2'). 
If your license is under SSA, which is already over, you also have to pay the time between the old SSA date and the current SSA end date twice.

Here is a short example, how the days are calculated:

Bind date: 24/06/2009 
Current date: 31/08/2009 
SSA end date: 12/12/2011 
 
You will have to pay from 24/06/2009 to 31/08/2009 twice for 68 days.
From 31/08/2009 to 12/12/2011 you will then have to pay the normal price for 833 days.

You can also select for each license, if you want SSA for it or not. If not, no SSC is needed and no (new) SSA end date is set for this license. 

You can preview the SSC calculation for another calculation date. Simply change the dropdown
selection to get the new SSC value.
Of course you can't confirm this calculation for another date, just for the current date!

''You may add additional licenses to the calculation, which you will bind later''. Just click on the '''+''' near this text and you can add
multiple licenses, which will be added to your calculation after using the recalc link. Listed are licenses of the current version and from
your balance.

After confirming your entered SSA end date, each license will have this date as SSA end date and can be downloaded in all versions of this SSA time.

You can now extend the projects SSA end date like as setting a new one.
The resulting summary is the same as above.

If your user account has the right to buy licenses on credit, just check the checkbox.
You may enter an order number, which you can use for your order, if you buy on credit.

=====Past SSA end date=====

You can configure a new SSA end date in the past, if you accidentally configured a wrong date. 
No licenses will be changed, if you configure a date in the past, just the SSA end date of the project!

=====SSA Expiry Mail=====

If project SSA will expire, each company user will receive a reminder mail '''7''' weeks before and
then every week one mail.
You can disable these mails with the checkbox 'Send SSA expiry mails'.
Note that every user can configure, if he wants to receive mails or not in his account settings.

If you want the end user of the project to receive an expiry mail, you can configure a '''reseller''' mail address and end user mail addresses. These end users will then receive an email, 30 days before the project will expire. The default text is:

Your Software Service Agreement for your innovaphone PBX in project "{$arg[3]}" will expire in {$arg[1]} days.
Please contact your reseller {$arg[2]} to upgrade the license. 
The upgrade of the license is important to secure the phone system!

You can change this text as you want. You can use placeholders:
* '''{$arg[1]}''': days left
* '''{$arg[2]}''': reseller mail address
* '''{$arg[3]}''': project name
 
You can also define a global text for all projects under your [[#Company| Company settings]].

You can optionally configure to receive project SSA independent reminder mails for each license of a device [[#Company 2|here]].

=====Automatic SSA Extension Service=====

You can request an automatic SSA extension service for a project, which is under SSA. By following this link, you will have the opportunity to request a callback and/or the necessary agreement as PDF file.

All licenses have to be under SSA to use the automatic SSA extension service!

There are some basics to know, if a project is under automatic SSA:
* If you bind new/free licenses, they'll get SSA until the current project SSA date and you will receive an invoice for the SSCs
* If you move devices into this project, their licenses will get SSA until the current project SSA date and you will receive an invoice for the SSCs
* You can't join this project into another project, but you can join another project into this one

====Rights====
=====Own project=====
Add or delete company rights for this project. To add a company right, you have to enter the company id of this company.
Each user of a company with rights on this project can add devices, licenses, activation keys to this specific project, but is restricted in removing devices, editing the project and can't create activation keys with the projects balance.

The company id can be found under Licenses->company and the company tab.

[[Image:Project_rights.jpg|center|thumb|200px|project_rights.jpg/|project_rights.jpg/]]

=====External Project=====
If another company granted access rights to a project to you, you can unsubscribe from this project here.

====Import====
The import has been disabled. All old devices are already imported and can be added to your project manually.

====Join====
Here you can join your currently selected project with another project, which you select from a dropdown box. 
If the other project has SSA, you'll see the current SSA end date, which you might change for the join process and you will get a list of all licenses, which might be updated to the ssa end date/changed date of the other project. The list equals the list shown under [[#Software Service|Software Service]].

The selected project will be automatically deleted after the join. You can't join a project,
if it grants external rights to another customer. Delete these rights before.

You can't change the SSA end date, if the other project is under automatic SSA! You will receive an invoice for SSCs used for the join.

====Project Move (admin only)====
A company admin can move a project with its devices, activation keys, balance etc. to another company. You have to know the company ID from this company, which can be found under Licenses->Company and the company tab. 
The history won't be moved!

Projects with negative balances can't be moved!

Existing project rights will be deleted.

====Delete====
Delete the project. Only possible if it has no activation keys, project rights, devices or user rights.
 
You may [[#Join|join]] your project into another one, if you can't delete it.

====Project Freed_RMA_licenses====
If you see a project with this name in your project list, you had a RMA device with not yed moved licenses, which was shipped to innovaphone and reshipped to another customer. 
The licenses of such a device have been moved into the pool of free licenses of the project Freed_RMA_licenses, from where you can assign them to another device.

====Rental====
Projects starting and ending with the '''$''' sign in their name are rental projects. 
The name corresponds to the domain name of a Devices App installation. 
 
All software licensing and device management can be just done through the Devices App itself, see [[Reference13r1:Concept_App_Service_Devices#Rental_program_and_Payment_method]]. 
Just '''hardware licenses''' still need to be bound inside my.innovaphone currently and have to be downloaded there and uploaded on the device itself just as usual.

===Balance===
On the balance page you will see the balance of the currently selected project or the balance of all your projects together.
The balance is bound to your company and '''not''' to your user account. The balance is bound to a specific project, but can be shared for license creation or activation key creation if wished. 
Sharing the balance over several projects is not possible in external projects!

[[Image:Balancepage.jpg|center|thumb|200px|balancepage.jpg/|balancepage.jpg/]]

====Free licenses====

Here you see a list of all your free licenses. If you return licenses from one of your devices, the returned licenses are stored in your free licenses pool. You can assign these licenses to another device (see [[#Add licenses from free licenses|'Add licenses from free licenses']]).

[[Image:Balance_free_lics.jpg|center|thumb|200px|balance_free_lics.jpg/|balance_free_lics.jpg/]]

The bind date, SSA end date and the external key (like DECT-Multi-Cell-Ari) are stored for each license.

===Activations===

You'll see a list of all your bound activation keys with their licenses here.

[[Image:Activations.jpg|center|thumb|200px|activations.jpg/|activations.jpg/]]

====Add an activation key====
To increase your projects balance, select one of your projects, follow the "Add" link and enter the activation key in the corresponding field. You can also enter an optional comment for this key. You will then get a listing of all contained licenses. After commiting this key, your project balance will have been increased by the keys values.

"Deselect the current project" to view all activation keys independent of the selected project.

====Search for an activation key by your order number====
Enter your own order number (or nothing), to view your activation keys for this order.

====License certificate====
You can always download the innovaphone license certificate for activation keys in your projects. Simply press the download link in the list at the right side.

===Own Activations===
Here you'll see a list of all created activation keys in the selected project (or over all projects).

You can create activation keys on the project page for other users/companies or to simply transfer licenses from one project to another. 
You can enter a comment, an order number and an order reference. The '''order number''' is your own order number for the key and the '''order reference''' is the reference number of the customer, who receives the newly created key. 
The order reference and order number will be shown in the innovaphone license certificate.

[[Image:Created_activations.jpg|center|thumb|200px|created_activations.jpg/|created_activations.jpg/]]

You have to select an activation key in the activation key list to update or delete it.

Updating and deleting a key is only possible, if this key is not assigned.

====Update====
Add more licenses to this key or change its comment, order number and order reference. 
You can also remove licenses by entering e.g. -2, if you want to remove 2 licenses from the key.

[[Image:Own activations update.jpg|center|thumb|200px|own_activations_update.jpg/|own_activations_update.jpg/]]

====Delete====
Delete this key. Its licenses will go back into the balance of the currently selected project.

===Devices===
To view your devices you first have to click on the "Show" button. You can leave the filter field empty if you want to view all your devices.

[[Image:Devices_page.jpg|center|thumb|200px|devices_page.jpg/|devices_page.jpg/]]

Red marked device names are devices, which are currently in RMA.

MAC addresses of RMA devices do not longer start with 01-...

====List====
A List of your devices in the currently selected project. 
You can deselect the current project/device to list all your devices.

Select a certain device from the device list, to manage its properties, licenses etc.

Actions on multiple devices:
* Move: move several devices into another project at once (see [[#Move device|Move Device]])
* Remove: remove several devices at once (see [[#Remove|Remove]])

=====Add=====
Follow the "Add new devices" link on the devices page.

There you have a few options:
* You can add a single new device
* You can add devices according to a mac address range (e.g. from 00-90-33-08-20-00 to 00-90-33-08-22-00), maximum 50 at once
* You can add devices by uploading a text file with mac addresses like this (maximum 50 at once, each line one mac):

00-90-33-08-20-20
00-90-33-08-20-21
00-90-33-08-20-22
00-90-33-24-20-20

* You can add devices according to your received order number. Just enter you order number and you will get a list of all devices bount to this number.

Note: MAC addresses can be always given like this:
* 00-90-33-xx-xx-xx
* 00:90:33:xx:xx:xx
* 009033xxxxxx
* xxxxxx (00-90-33- will then be added automatically)

There might be errors, if you try to add a device. They are explained [[#Image explanation|here]].

As the device warranty will be handled by licenses now, you can also add telephone devices
to your projects.

=====Add warranty extensions=====

Here you can add warranty extension licenses for all devices in the currently selected project. 
You'll get a list of all devices with the corresponding license type(s) and you can specify the years for each device (or for all devices by entering the number in the list header). 
After confirming your selection, you'll get an overview of all needed licenses, which you have to confirm too.

=====Check licence, SSA and warranty status of a device=====
Here you can list licenses with ssa and the warranty end date of a device, which is not in one of your projects. 
For this option to work, you have to link your innovaphone customer ID (5 digits) to your my.innovaphone company. (As the warranty is also the one we grant to our distributors, we don't want to get an end customer confused.)

=====Download devices of an order as CSV=====
Enter an order number to retrieve all devices for this order in a CSV file.

=====Download devices of an order as PDF with barcodes=====
Enter an order number to retrieve all devices for this order in a PDF file with a barcode for each MAC address. 
Der Barcode ist vom Typ C128B.

====Properties====

Change the name and comment of a device.
You can only change the name, if it's no MAC or IPEI.
 
Here you have also the possibility, to directly request RMA for this device with prefilled values.

====Licenses====
Here you can add, download or move licenses.

=====Add licenses from balance=====
To create new licenses for a device, you have to add this device first on the devices page and then select a version of the license
and whether you want to summate the current licencing. If you select current licenses, then older licenses for example V6 or V7 licenses will also be counted as V8 licenses in the next overview. This is necessary if you want to license a V6 unit with V8 licenses, but still want to use it as V6.
After that click "Next".
On the next page you will see a list of all available license types, which depends on your current available license types, of the selected license version and the device type (IP6000, IP800 e.g.):
[[Image:licenses.jpg|center|thumb|200px|licenses.jpg/|licenses.jpg/]]
 
If your project has a SSA end date, which is not yet over, you'll have the possibility to set SSA for the new licenses to this SSA end date or you can optionally change this date to another one for the new licenses.
 
You see the available project balance, the balance over all projects (excluding external projects), the currently installed licenses and the maximum amount for this device type. You can now enter the value of the new license.
Base/Upgrade licenses can be selected via dropdown box.
'''Voicemail and Standby lics must always have the same amount as the selected PBX-PBX... license!
The maximum amount of PBX-Registration licenses equals the amount of the selected PBX-PBX... license!'''

The whished overall amount of pbx version 8 and above licenses can be specified here and the concrete amount of license sub types will be requested on the next page.

You can preview the SSC calculation of the wished licenses without having them in your balance.

[[Image:licenses2.jpg|center|thumb|200px|licenses2.jpg/|licenses2.jpg/]]

The best (cheapest) combination of each v8 pbx license type is already filled in, but you might change the amount of sub types if your does not fit and you do not want to purchase new activation keys for the sub types.

The column SSC/Unit is just shown if your project is currently under SSA and you have entered a SSA end date.

The SSC multiplicator is the value, which you have to multiplicate with each license unit to get
the corresponding SSC amount.
E.g. if you have 20 units of PBX-Port8*20 licenses with a SSC value of 54 and a multiplicator of
1.0000 (which equals to 365 days) you have to pay 20*54*1.0000 ~ 1080 SSCs.

 If you create licenses for an older version than the current version, you have to pay SSCs from the [[#Release dates|release date]] of the next version of the currently selected version twice. 
e.g.: you want to bind licenses for V6 with SSA, so you have to pay SSCs from the release date of V7
 You can also select for each license, if you want SSA for it or not. If not, no SSC is needed and no (new) SSA end date is set for this license. 

You can't change the SSA end date, if the project is under automatic SSA! You will receive an invoice for SSCs used for the new binding.

Now confirm your new selection. If you have not enough licenses in your current project, but there are still licenses in other projects, you will get a dropdown box with a list of all projects containing the needed licenses. You can now select all desired/needed projects and confirm your selection again.
The balance of all selected projects will then be decreased by the needed amount.
 
 
If your user account has the right to buy licenses on credit, just check the checkbox.
 
You may enter an order number, which you can use for your order, if you buy on credit.

=====Add licenses from free licenses=====

Here you can assign licenses, which you returned from other devices.
You will also have to select the desired version and will than get a list of fitting licenses according to the current device and selected version.

[[Image:licenses_free.jpg|center|thumb|200px|licenses_free.jpg/|licenses_free.jpg/]]

If a license is under SSA, the correct license type is shown in column 'License Type' besides the 'Original Type'.
On confirming the selection, a consistency check is done (e.g. only 4 Relay-PRI licenses on an IP6000).
Bind and SSA end date will be maintained for each license.

As external keys are also maintained, you can select e.g. an old Dect-Multicell-Ari license to have the same ARI on another IP1200.
 

If your project has a SSA end date, which is not yet over, you'll have the possibility to set SSA for the new licenses
to this SSA end date or you can optionally change this date to another one for the new licenses.
You will have to confirm this after your first license selection (this is the same calculation as [[#Software Service|here]]).

You can't change the SSA end date, if the project is under automatic SSA! You will receive an invoice for SSCs used for the binding.

=====Add V7 floating license (slave pbx)=====
Here you can add a V7 floating license for a slave pbx. A device with a floating license can't have V7 pbx licenses and a device with V7 pbx licenses can't have a floating license.

=====Delete V7 floating license=====
Here you can delete an already existing floating license, if you won't use it anymore.

=====Add warranty extension licenses=====
Extend your warranty by adding warranty extension licenses:

[[Image:add_warranty.jpg|center|thumb|200px|add_warranty.jpg/|add_warranty.jpg/]]

If you add the warranty extension immediately after the receipt of your device,
you can add the cheaper warranty extension licenses, otherwise you'll have to add
the more expensive ones.

You can extend the warranty for a maximum of four years.

=====Download licenses=====

[[Image:Device_download.jpg|center|thumb|200px|device_download.jpg/|device_download.jpg/]]

You will get a dropdown with all available versions. Versions are dependent of your device, your licenses and of the ssa of your licenses. 
'''From V9 on''', you just have one option, which will create a license file, which contains the licenses upgraded to the highest version of their type. 
You are able to download downgraded versions of your licenses. E.g. if you have only V8 licenses, you can download a V7 license file (same restrictions as below).

Downgrades or only possible down to version 6!

If you do not want to download licenses by version, you have to decide whether to download the licenses encrypted or not.
'''If you download the licenses unencrypted, you won't be able to return those licenses anymore.'''
So you won't be able to return licenses for devices with V5-V7 licenses, as licenses for these versions are not encrypted.
To return these licenses, you will have to upgrade to a new bootcode, which prevents firmware downgrades to versions below version 8. 
Encrypted licenses are stored in a xml file, which you can then upload on your V8 (or higher) device.

You can now also download licenses directly from by the web interface of a device.
You just have to enter your account data and start downloading the licenses from my.innovaphone.com
without having to download/upload a license file.

=====Download test licenses=====

[[Image:Device_download_test.jpg|center|thumb|200px|device_download_test.jpg/|device_download_test.jpg/]]

You can also download test licenses if you want to run tests. You will be asked, which version you want to use, whether the device is used as slave and if not used as slave, how many pbx licenses you want to use.

'''Important: Since V11, trial licenses are valid for 3 months and can be released once for a dedicated device. After expiration of those 3 months no further trial license creation for this device is possible.'''

V5 does '''not''' support test licenses!

=====Download App development license=====
If you're an App developer, you have the possibility, to generate a real license for you Apps which will contain your manufacturer prefix. 
The manufacturer prefix has to deposited at your my.innovaphone company by innovaphone before you can use this feature.

You can just have up to '''three''' different devices per company for which you can create such licenses!
These licenses aren't allowed for production usage!

You see your already used MAC addresses on this page too if you already created such licenses before.

If your manufacturer prefix is '''innovaphone''', you can enter license names like:
* App(innovaphone-app1)15
* Service(innovaphone-app2)15

=====Move licenses to another device=====
If you have the needed account rights or the device is already in RMA, you can move licenses to another device. After moving licenses, the former device will be marked as a RMA device.

You can just move licenses to devices without licenses!

=====Mix of rental and purchased licenses=====
From '''13r2 SR12''' onwards you can mix rental and purchased licenses. 
A device with rental licenses will be always inside a rental project (you recognize such a project by it's starting and ending '''$''' in the name). 
You can now add licenses from the balance to a device in such a rental project. 
 
If you invalidate lifetime licenses on such a device, just purchased licenses are returned. Rental licenses stay bound until you remove them inside your Devices App! (under rental menu)
Inside my.innovaphone you will always see both rental and purchased licenses. Inside the Devices App, you will just see the rental licenses. 
 
You must download and/or install the purchased licenses as usual. 
 
A 13r1 PBX or a PBX with an older SR will just recognize rented licenses!

If your PBX is already inside a non rental project, it will be automatically added to a rental project if you add rental licenses. You then may have the device in two different projects (one rental, one normal), which is no issue.

====Move device====
Here you can move the current device or the selected devices to another project. 
If you select a SSA project, you can change the SSA end date for the move process. 

If the other project is under SSA, you will first see a SSC calculation, which you have to confirm,
as the SSA date for each SSA license will be extended until the given SSA end date
(this is the same calculation as adding SSA to an already existing project, see [[#Software Service|here]]).

You can't change the SSA end date, if the other project is under automatic SSA! You will receive an invoice for SSCs used for the move.

====Invalidation====
====Returning of licenses====

By the invalidation, licenses are returned to the free balance of the project to which the device belongs in the Portal my.innovaphone. 
You can then bind the licenses from the free balance to another device.

=====Requirements=====
* V8 or higher
* access to the webinterface
* a device certificate
* my.innovaphone login credentials
* '''no IPVA device'''
* no 'In House' licenses

=====Informations=====

You can invalidate V8 (or higher) licenses by uploading the XML file, you got from your device or by returning your licenses over the web interface of your device ([[Reference8:Configuration/General/License]]), in order to return [[Reference8:Licenses#Gateway Licenses|PBX licenses]] back to the free balance.

V7 licenses can be just returned, if you agree, that you won't be able to downgrade below V8 anymore. You will need a new bootcode, to use this function. '''You need a V8 firmware or higher for invalidation.'''

If your device has access to my.innovaphone.com, you can also invalidate licenses directly
from the web interface of the device.

[[Reference8:Licenses#Gateway Licenses|gateway licenses]] and warranty extensions won't be returned to the balance and remain to be assigned to the device!

The licenses needn't be present on the local device to perform the invalidation!

SSA it's bound to the license and it's not lost when performing invalidation.

=====Process=====

Steps to invalidate licenses, if your device has internet connectivity:
# on the web interface of the device go to General->License and follow the my.innovaphone link
# enter your my.innovaphone account, the device must be in one of your projects
# click Invalidate
# click Transfer (this might fail, if NTP or DNS is not configured properly or device certificate is not installed)
# reset if asked for

Steps to invalidate licenses, if your device has no internet connectivity:
# on the web interface of the device go to General->License and follow the my.innovaphone link
# click Invalidate
# click Backup and upload this file on my.innovaphone [[#Upload the invalidation document to return licenses|here]] (Licenses->Devices (select the corresponding device)->Invalidation)
# you'll get a confirmation file after uploading the saved file
# upload this on the device (under Step1)
# reset if asked for

"Your IP800 does not have a device certificate on it." - In this case you need to download a hardware certification,
please contact the innovaphone [mailto:license@innovaphone.com license].

=====Download confirmation file=====
If you created a new certificate or you invalidated your licenses, you can later download the confirmation file, which you have to upload on the box.

=====Request certificate=====
If you have the needed rights, you can request a new device certificate for your device.

=====Upload the invalidation document to return licenses=====
Licenses->Devices (select the corresponding device)->Invalidation:

Upload the invalidation document, which you got from the website of the device to return the licenses of this device.

After uploading you'll get a confirmation file, which you have to upload on your device.

====Remove====
You can always remove devices from a project. If they have licenses, these won't be deleted, so you might add the device to another project again.

===History===
[[Image:history.jpg|center|thumb|200px|history.jpg/|history.jpg/]]
You can view your history for several contexts:
* Company: history of all actions in your company
* User: history of all actions of the selected user
* Device: history of all actions for the selected device

Each context applies to the currently selected project.
If you deselect the current project, you will see the history over all projects.

You can select to view the history of the last day, week, month, year or from always. Collecting data might take a while...

===Company===
Manage users SSA expiry email flag, import other companies or add your companies innovaphone ID.

====Users====

You can just edit the SSA expiry email flag here. The other user settings moved to the [[#Authorized Persons| Authorized persons tab]].

====Join (admin only)====
As admin you can also join another company into your company by entering an admin account of this company. This might be usefull if one user of your company has accidentally created an own company. 
Everything like projects, users, devices, balance, activations etc. will be imported! 
You also have to enter the company id of the company, which is to be imported. You can find this company under Licenses->Company and the company tab.

This is not available for non company admin users.

The joined company will be deleted afterwards!

====Company====

You can check the '''Device SSA''' checkbox, if you want to receive SSA expiry reminder mails for each device independent of the projects SSA end date.
These mails will be send weekly seven weeks before the SSA for a license a the device expires.
 
 
You can also enter additional email addresses, which should receive SSA emails.
 
You can define a global '''end user expiry mail text''' here, which will be sent to end users, if end users are configured in a [[#SSA Expiry Mail| project]]. This text can be overridden by a text in a project under [[#SSA Expiry Mail| SSA Expiry Mail]].

==RMA==
Here you can see all your RMA devices, which arrived innovaphone already. The licenses of this macadresses are moveable.
[[Image:rma.jpg|center|thumb|200px|rma.jpg/|rma.jpg/]]
 
If you want to request RMA for a certain device, go to the device properties and follow the "Request RMA" link.

==Support==
===Mantis===
Here you'll get a list of all open cases and [[Understanding the innovaphone trouble ticket status page#Information available| additional info regarding their state]] in our ticket system. This list is composed of all tickets assigned to email addresses of your my.innovaphone users in your company. 
Often used functions:
* You can click on the ticket number ("ID" column) to open an email prepared with the right emailadress and subject to address this case.
* You can click on the ''History'' link to get an overview of the already made communication with our support/presales-team.
* Another important new function is the option to upload larger files to your support/presales tickets using the ''Fileupload'' column.

===Announcements===
You can convert audio files into G.7xx files which you can use as announcements. 
 
;Supported input formats:
* mp3
* wav
* ogg
* flac
* ...

;Generated output formats:
* G.711u
* G.711a
* G.729
* G.723
* G.722

==Image explanation==

===Errors===

====Already In Company====
[[Image:Icon_in_company_inno_01.png|icon_in_company_inno_01.png/|icon_in_company_inno_01.png/]]
* This device already exists in your company and can't be added/imported.
If you want to import this device anyway, you first have to delete your current device from its project.

====Already Imported====
[[Image:Icon_imported_inno_01.png|icon_imported_inno_01.png/|icon_imported_inno_01.png/]]
* This device has been already imported.
You can't import it again.

====Not Found====
[[Image:Icon_not_found_inno_01.png|icon_not_found_inno_01.png/|icon_not_found_inno_01.png/]]
* This device was not found in the my innovaphone database.
This should never happen, but if, contact the administrator.

====IPVA MAC exists====
[[Image:Icon_ip_va_exists_inno_01.png|icon_ip_va_exists_inno_01.png/|icon_ip_va_exists_inno_01.png/]]
* An IPVA MAC address must be unique and can be assigned to just one company. You tried to add an already existing IPVA MAC.
Please assign a new one to your IPVA. For further details, see [[Reference13r2:Concept_Innovaphone_Virtual_Appliance#License_Configuration]].

my.innovaphone supports the following MAC address ranges:
* 00-50-56-...
* 00-15-5d-...
* 00-03-ff-...
* 00-0d-3a-...
* 00-12-5a-...
* 00-17-fa-...
* 00-50-f2-...
* 00-1d-d8-...
* 00-05-69-...
* 00-1c-14-...
* 00-0c-29-...
* 00-1d-db-...
* 5a-ad-1d-...
* 48-e9-ca-...
* bc-24-...
* e2-... ''this is an autogenerated MAC address of innovaphone cloud containers''

===Warnings===

====Several Companies====
[[Image:Icon_several_companies_inno_01.png|icon_several_companies_inno_01.png/|icon_several_companies_inno_01.png/]]
* This device is already in another company.
This means, that either you do not have the physical device or it once belonged another company.
You can still import/add this device and you will have access to all of its current licenses.

====Several Users====
[[Image:Icon several users inno 01.png|icon_several_users_inno_01.png/|icon_several_users_inno_01.png/]]
* This device has licenses from several users of the old license manager.
This means, that you are not neccessarily the user, who physically owns this device. If you do not own it, do not import it.

===Misc===
====No downgrade====
[[Image:no_downgrade.png|no_downgrade.png/|no_downgrade.png/]]
* Licenses, which have been downloaded for V5/V6/V7, were returned from this device, so no downgrade to these versions is allowed any more.



==Release dates==
V5: January 1st 2003 
V6: November 2nd 2006 
V7: November 14th 2008 
V8: December 7th 2009 
V9: April 26th 2011 
V10: July 8th 2013 
V11: February 9th 2015 
V12: July 11th 2016 
V13: May 13th 2019 
V14: December 20th 2023

V15: March 25th 2025 



==External interface==

There is an external interface, which you can use to control some functionality without a login to the my.innovaphone web site. 
You can use the interface with an '''HTTP GET''' request to the following URL: 
 
'''<code>https://my.innovaphone.com/interface.php</code>'''

Configure a trust value and a URL (can be a dummy URL if not used otherwise) unter Licenses -> Project -> Properties and tick "Configure Update-URL"

===General parameters for all commands===
:;cmd: the wished command
:;email: the email address of a user who is registered in my.innovaphone
:;project_id: the project ID of the project where the user has access to (you can find the project ID under [[#Properties| Licenses->Projects->Properties]])
:;hash: an SHA256 hash value which is computed over all GET parameters but the hash parameter itself plus the '''trust''' value of the project (see [[#Properties|Reference:My_Innovaphone#Properties]])
:;hash: the values of the GET parameters have to be URL encoded before calculation of the hash

;Example: URL <code>https://my.innovaphone.com/interface.php?cmd=addDevice&email=user@example.com&project_id=123456&serial=00-90-33-01-02-03&hash=b62f7948d6383cc365592ed289b6173cd35229cadc347847b953f78c8880d5b9</code>
:;project trust value: 1234567890abcdef
:;the data of the SHA256 hash: ?cmd=addDevice&email=user%40example.com&project_id=123456&serial=00-90-33-01-02-03&trust=1234567890abcdef
:;example PHP function call to generate the hash: hash("sha256", "?cmd=addDevice&email=user%40example.com&project_id=123456&serial=00-90-33-01-02-03&trust=1234567890abcdef");
:;with the current values, the function should return: b62f7948d6383cc365592ed289b6173cd35229cadc347847b953f78c8880d5b9

===Add a device to a project===
;HTTP GET parameters:
:;general parameters
:;cmd: '''addDevice'''
:;serial: the serial number of the device, e.g. 00-90-33-01-02-03
:;[device_desc]: optional, a description for the new device

;Return value: a JSON object is returned
:;success: boolean, either '''true''' or '''false'''
:;error: string, a string with an error. Just existent if success is false
:;example success: <syntaxhighlight lang="javascript">{ "success":true }</syntaxhighlight>
:;example error: <syntaxhighlight lang="javascript">{ "success":false, "error":"the project with ID 123456 doesn't exist" }</syntaxhighlight>

===Remove a device from a project===
;HTTP GET parameters:
:;general parameters
:;cmd: '''delDevice'''
:;serial: the serial number of the device, e.g. 00-90-33-01-02-03

;Return value: a JSON object is returned
:;success: boolean, either '''true''' or '''false'''
:;error: string, a string with an error. Just existent if success is false
:;example success: <syntaxhighlight lang="javascript">{ "success":true }</syntaxhighlight>
:;example error: <syntaxhighlight lang="javascript">{ "success":false, "error":"the project with ID 123456 doesn't exist" }</syntaxhighlight>

===Get the warranty of a device===
;HTTP GET parameters:
:;general parameters
:;cmd: '''getWarranty'''
:;serial: the serial number of the device, e.g. 00-90-33-01-02-03

;Return value: a JSON object is returned
:;success: boolean, either '''true''' or '''false'''
:;error: string, a string with an error. Just existent if success is false
:;warranty: a unix timestamp in seconds since 1970 (timezone Europe/Berlin), e.g. '''1448492400'''
:;warrantyStr: a string like '''"2015-11-26 00:00:00"'''

===Create a new project===
;HTTP GET parameters:
:;general parameters: you must use the project_id and trust value of an already existing project!
:;cmd: '''createProject'''
:;project_name: the name of the new project
:;[project_desc]: optional, a description for the new project
:;[update_url]: optional, an update URL for the project (do not forget to URL encode the value inside your HTTP GET request!)
:;[ssa_due_date]: optional, a unix timestamp in seconds since 1970 (timezone Europe/Berlin), e.g. '''1448492400'''

;Return value: a JSON object is returned
:;success: boolean, either '''true''' or '''false'''
:;error: string, a string with an error. Just existent if success is false
:;projectId: the project id of the created project

The newly created project is created with the same trust value which was used for the creation request. This allows you to directly use the API with the new project.

==Known Issues==
===Smaller issues===
* Devices where imported into a project with SSA. If this happened to you, please move the corresponding devices into a project '''without''' SSA and back into the project '''with''' SSA to extend/add SSA for the licenses until the SSA end date.
* IE7 moves a list under the menu, when a list becomes to wide
===Licenses don't work on a device, where an invalidation has been done===
A possible reason here is, that the invalidation process hasn't been completed.
To resolve this issue, follow these steps:

* Download the Confirmation File (Certificate) from http://my.innovaphone.com under [[#Invalidation|Invalidation]] after selecting the project and the device
* Open [[Reference9:General/License/my.innovaphone|General->License->my.innovaphone.com]] on your device
* Click on "Invalidate" (no my.innovaphone credentials needed)
* Upload the previously downloaded confirmation file newcert-00-90-33-xx-xx-xx.xml as "Confirmation file"
* Reset the box
* Reupload the licenses

===Internet Explorer doesn't work===
Yes, that's correct. Please use an up to date version of Chrome, Firefox or Edge!

Reference:My Innovaphone

2025-08-06T07:32:15Z

Dde: /* Informations */

==Where is my old my.innovaphone?==
Don't worry, just login with your old my.innovaphone account! You will be asked to confirm your forename and surname (just a '''natural person''' is allowed) and accept some terms and conditions. 
Afterwards you find the old license/device view inside the [[#Licenses tab| Licenses tab]].

==About==
my.innovaphone allows the handling of licenses and includes the handling of device warranty and software service agreements. 
You can also sign contracts here for different purposes.

===Project-View===
My innovaphone offers the possibility for several users to be in one company. This company shares its balance of licenses over all users and can have several projects. Projects have their own balance of license types and devices are bound to a project.

===Language===
My innovaphone will support multiple languages. You can select your desired language at the top of the page. 
Currently supported languages:
* English
* German
* Italian
* Dutch
* French
* Spanish (partially)
* Polish (partially)

===Guides===

====Quickstart guide====
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_nl.pdf Dutch quickstart guide] 
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_en.pdf English quickstart guide] 
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_fr.pdf French quickstart guide] 
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_de.pdf German quickstart guide] 
[https://my.innovaphone.com/docs/my_innovaphone_Quick_Start_Guide_it.pdf Italian quickstart guide] 

====SSA guide====
;V10 and greater:
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10nl.pdf Dutch SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10en.pdf English SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10fr.pdf French SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10de.pdf German SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10it.pdf Italian SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10pl.pdf Polish SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_V10es.pdf Spanish SSA guide] 

;V8 and greater:
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_en.pdf English SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_fr.pdf French SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_de.pdf German SSA guide] 
* [https://my.innovaphone.com/docs/innovaphone_SSA_Leitfaden_it.pdf Italian SSA guide] 

==First steps==
Open [https://my.innovaphone.com my.innovaphone.com] and click the "I would like to create a new personal user account" link.
Enter your personal data and register.

You will receive a registration email with an activation link.
After account activation you have two options:
* create a new my.innovaphone company with the "Create company account" button
* ask another user of your company to invite your email address to an already existing company

If you accidentally created an own my innovaphone company, just ask another user of your company to import your just created company.

If you create a new company, you can '''optionally''' enter your innovaphone account ID (which is your customer number with innovaphone) with your postal code, to retrieve your company data.

Inside the license tab of the my.innovaphone portal, you will see a help link at the right side of the horizontal tab menu.
This link shows the corresponding text of the wiki section, when hovering with the mouse over it,
and redirects to the corresponding wiki menu, if clicked.

It is possible, that one user is member of serveral companies!

==Left bar==
If you open the left bar, you have the options to:
* select one of your companies
* edit your personal user account
** user name
** email address
** flag to recieve SSA expiry emails
** password
* create a new company
[[Image:Myinnovaphone bar.png|center|thumb|200px|myinnovaphone_bar.png/|myinnovaphone_bar.png/]]

==Main tabs==
Inside each company you see the three main tabs:
* Contracts
* Authorized persons
* Licenses (see [[#Licenses tab| Licenses tab]])

You may also have two buttons:
* Add Contract (just as company administrator or with the contract right)
* Invite person (just as company administrator)

[[Image:Myinnovaphone main.png|center|thumb|200px|myinnovaphone_main.png/|myinnovaphone_main.png/]]

=== Contracts ===
Inside the contracts tab, you see all your contracts and you can download these conracts. 
In general, contracts must be first approved by innovaphone, so you see three types of contracts:

* open contracts which must be approved by innovaphone first
* approved contracts which can be already used
* cancelled contracts which are not valid anymore

[[Image:Myinnovaphone contracts.png|center|thumb|200px|myinnovaphone_contracts.png/|myinnovaphone_contracts.png/]]

These type of contracts currently exist:
==== innovaphone myApps Cloud Service ====
Conclude this contract to use the innovaphone myApps Cloud.

==== innovaphone software rental ====
Conclude this contract to rent innovaphone software products. You must conclude this contract if you want to use the software rental inside the Devices App.

=== Authorized persons ===
Here you see all persons which exist inside your company. Each person can have the following rights:
* Administrator (everything)
* Contracts (can conclude contracts)
* Licenses (can work with licenses)
* Viewer (can just see everything without doing something)
* Locked (cannot even login to this company anymore)

=== Licenses ===
Here comes the old my.innovaphone view which allows the handling of devices, licenses, activation keys etc.

==Search (inside licenses tab)==
At the right top of the licenses tab you have a search field. You can search for different things:
* Devices (part of a device name or device comment)
* Projects (part of a project name or project description)
* Own activation keys (part of an activation key or its description)
* Hardware rental orders (part of the innovaphone order number or your own order reference or a MAC address of an order)

You have to enter at least '''three''' chars to start a search. To search for activation keys,
you have to enter at least '''five''' chars.
* Search for license types. Enter e.g. "PBX-Port8" to find all devices with Port8 licenses or enter "PBX-Port8=100" to find all devices with Port8 licenses '''>=''' 100.
* Search for products, e.g. 01-00811 für IP811 (such a search may take longer!)

==Licenses tab==
===Projects===
After creation of an own company, you will have a default project named "DEFAULT". You can rename this project later.
You can also create more projects on the projects page with "Create".
Each project of a company must have a unique name.

Do '''not''' set SSA, if you want to import your devices from your old license manager account first.
If you want SSA and you '''won't import''' devices into this project from your old account, you should set SSA at once.

You can select a certain project by activating it in the project list. This selection is then true for all other pages, as some pages require a selected project.

[[Image:overview.jpg|center|thumb|200px|overview.jpg/|overview.jpg/]]

By activating a project by clicking on the project name in the project list, you can manage this project and its settings.

==== Rental project ====
You can also manually create a rental project. A rental project is normally created automatically by uploading an activation key inside the Devices App. 
But if you want to start directly with an Automatic iSC reloading service, you'll need to create the project manually. 
Take care that the name '''equals''' the domain name in your Devices App. 
 
If the rental tab in your Devices App domain doesn't show the expected balance/Automatic iSC reloading contract/licenses etc., you may use the Devices App Guid Link mechanism to link the domain to this specific project (see below) (use Devices App '''13r3 SR12''' or higher!).

====Properties====
Rename the project or/and change its description. 
 
You can configure further CC mail addresses inside your '''License Purchase''' project, if you have one. If you purchase licenses on credit, the emails will be also sent to theses addresses.
 
 
Since version 10, an innovaphone device will automatically connect to http://config.innovaphone.com/init
This script looks at the project properties of the project, where the device exists. 
You can configure an update '''URL''' and a '''trusted certificate'''. 
 
;Devices App GUID link: This is a GUID which can be entered in the settings of a domain inside the Devices App to link the domain to this specific project, if the names do not match and/or the Devices App has been setup from scratch. The Devices App must use the customer to which this projects belongs to be able to use this GUID.

====Software Service====
You can put your project under SSA (software service agreement).
You will be asked to enter a SSA end date. This will be the date, where all SSA licenses of all devices in this project will expire.
The end date mustn't be more than one year in the past. 
Optionally you can enter a maximum SSC amount. The SSA end date will be automatically calculated then. 
If you have entered a maximum SSC amount, you have to use the '''Recalculate''' link to calculate a new SSA end date,
if you change your license selection.
 
You can also calculate SSA over all projects at once. In this mode, you '''won't be able''' to confirm the calculation. You'll just see the necessary SSC amount.

After entering a date/SSC amount, you will get a summary of all licenses, which will be put under SSA and the amount of needed SSC licenses.
The SSC value for each license is calculated by the bind date of the license and the entered SSA end date/SSC amount.

[[Image:Ssa_extend.jpg|center|thumb|200px|ssa_extend.jpg/|ssa_extend.jpg/]]

If you have licenses for an older version than the current version, you have to pay SSCs from the [[#Release dates|release date]] of the next version of the current license version. 

e.g. you have a V7 PBX-PBX7#15 license with bind date 1/1/2010. Version 8 was released on 7/12/2009, so SSA is
calculated from 7/12/2009 for this license. You will see the calculation date in the list under "bind date"

If licenses already have a SSA date, just the difference between the current SSA date and the entered SSA end date must be paid.
If the bind date of the device lies in the past, the difference between the bind date and the current date must be paided twice (this is the column 'days*2'). 
If your license is under SSA, which is already over, you also have to pay the time between the old SSA date and the current SSA end date twice.

Here is a short example, how the days are calculated:

Bind date: 24/06/2009 
Current date: 31/08/2009 
SSA end date: 12/12/2011 
 
You will have to pay from 24/06/2009 to 31/08/2009 twice for 68 days.
From 31/08/2009 to 12/12/2011 you will then have to pay the normal price for 833 days.

You can also select for each license, if you want SSA for it or not. If not, no SSC is needed and no (new) SSA end date is set for this license. 

You can preview the SSC calculation for another calculation date. Simply change the dropdown
selection to get the new SSC value.
Of course you can't confirm this calculation for another date, just for the current date!

''You may add additional licenses to the calculation, which you will bind later''. Just click on the '''+''' near this text and you can add
multiple licenses, which will be added to your calculation after using the recalc link. Listed are licenses of the current version and from
your balance.

After confirming your entered SSA end date, each license will have this date as SSA end date and can be downloaded in all versions of this SSA time.

You can now extend the projects SSA end date like as setting a new one.
The resulting summary is the same as above.

If your user account has the right to buy licenses on credit, just check the checkbox.
You may enter an order number, which you can use for your order, if you buy on credit.

=====Past SSA end date=====

You can configure a new SSA end date in the past, if you accidentally configured a wrong date. 
No licenses will be changed, if you configure a date in the past, just the SSA end date of the project!

=====SSA Expiry Mail=====

If project SSA will expire, each company user will receive a reminder mail '''7''' weeks before and
then every week one mail.
You can disable these mails with the checkbox 'Send SSA expiry mails'.
Note that every user can configure, if he wants to receive mails or not in his account settings.

If you want the end user of the project to receive an expiry mail, you can configure a '''reseller''' mail address and end user mail addresses. These end users will then receive an email, 30 days before the project will expire. The default text is:

Your Software Service Agreement for your innovaphone PBX in project "{$arg[3]}" will expire in {$arg[1]} days.
Please contact your reseller {$arg[2]} to upgrade the license. 
The upgrade of the license is important to secure the phone system!

You can change this text as you want. You can use placeholders:
* '''{$arg[1]}''': days left
* '''{$arg[2]}''': reseller mail address
* '''{$arg[3]}''': project name
 
You can also define a global text for all projects under your [[#Company| Company settings]].

You can optionally configure to receive project SSA independent reminder mails for each license of a device [[#Company 2|here]].

=====Automatic SSA Extension Service=====

You can request an automatic SSA extension service for a project, which is under SSA. By following this link, you will have the opportunity to request a callback and/or the necessary agreement as PDF file.

All licenses have to be under SSA to use the automatic SSA extension service!

There are some basics to know, if a project is under automatic SSA:
* If you bind new/free licenses, they'll get SSA until the current project SSA date and you will receive an invoice for the SSCs
* If you move devices into this project, their licenses will get SSA until the current project SSA date and you will receive an invoice for the SSCs
* You can't join this project into another project, but you can join another project into this one

====Rights====
=====Own project=====
Add or delete company rights for this project. To add a company right, you have to enter the company id of this company.
Each user of a company with rights on this project can add devices, licenses, activation keys to this specific project, but is restricted in removing devices, editing the project and can't create activation keys with the projects balance.

The company id can be found under Licenses->company and the company tab.

[[Image:Project_rights.jpg|center|thumb|200px|project_rights.jpg/|project_rights.jpg/]]

=====External Project=====
If another company granted access rights to a project to you, you can unsubscribe from this project here.

====Import====
The import has been disabled. All old devices are already imported and can be added to your project manually.

====Join====
Here you can join your currently selected project with another project, which you select from a dropdown box. 
If the other project has SSA, you'll see the current SSA end date, which you might change for the join process and you will get a list of all licenses, which might be updated to the ssa end date/changed date of the other project. The list equals the list shown under [[#Software Service|Software Service]].

The selected project will be automatically deleted after the join. You can't join a project,
if it grants external rights to another customer. Delete these rights before.

You can't change the SSA end date, if the other project is under automatic SSA! You will receive an invoice for SSCs used for the join.

====Project Move (admin only)====
A company admin can move a project with its devices, activation keys, balance etc. to another company. You have to know the company ID from this company, which can be found under Licenses->Company and the company tab. 
The history won't be moved!

Projects with negative balances can't be moved!

Existing project rights will be deleted.

====Delete====
Delete the project. Only possible if it has no activation keys, project rights, devices or user rights.
 
You may [[#Join|join]] your project into another one, if you can't delete it.

====Project Freed_RMA_licenses====
If you see a project with this name in your project list, you had a RMA device with not yed moved licenses, which was shipped to innovaphone and reshipped to another customer. 
The licenses of such a device have been moved into the pool of free licenses of the project Freed_RMA_licenses, from where you can assign them to another device.

====Rental====
Projects starting and ending with the '''$''' sign in their name are rental projects. 
The name corresponds to the domain name of a Devices App installation. 
 
All software licensing and device management can be just done through the Devices App itself, see [[Reference13r1:Concept_App_Service_Devices#Rental_program_and_Payment_method]]. 
Just '''hardware licenses''' still need to be bound inside my.innovaphone currently and have to be downloaded there and uploaded on the device itself just as usual.

===Balance===
On the balance page you will see the balance of the currently selected project or the balance of all your projects together.
The balance is bound to your company and '''not''' to your user account. The balance is bound to a specific project, but can be shared for license creation or activation key creation if wished. 
Sharing the balance over several projects is not possible in external projects!

[[Image:Balancepage.jpg|center|thumb|200px|balancepage.jpg/|balancepage.jpg/]]

====Free licenses====

Here you see a list of all your free licenses. If you return licenses from one of your devices, the returned licenses are stored in your free licenses pool. You can assign these licenses to another device (see [[#Add licenses from free licenses|'Add licenses from free licenses']]).

[[Image:Balance_free_lics.jpg|center|thumb|200px|balance_free_lics.jpg/|balance_free_lics.jpg/]]

The bind date, SSA end date and the external key (like DECT-Multi-Cell-Ari) are stored for each license.

===Activations===

You'll see a list of all your bound activation keys with their licenses here.

[[Image:Activations.jpg|center|thumb|200px|activations.jpg/|activations.jpg/]]

====Add an activation key====
To increase your projects balance, select one of your projects, follow the "Add" link and enter the activation key in the corresponding field. You can also enter an optional comment for this key. You will then get a listing of all contained licenses. After commiting this key, your project balance will have been increased by the keys values.

"Deselect the current project" to view all activation keys independent of the selected project.

====Search for an activation key by your order number====
Enter your own order number (or nothing), to view your activation keys for this order.

====License certificate====
You can always download the innovaphone license certificate for activation keys in your projects. Simply press the download link in the list at the right side.

===Own Activations===
Here you'll see a list of all created activation keys in the selected project (or over all projects).

You can create activation keys on the project page for other users/companies or to simply transfer licenses from one project to another. 
You can enter a comment, an order number and an order reference. The '''order number''' is your own order number for the key and the '''order reference''' is the reference number of the customer, who receives the newly created key. 
The order reference and order number will be shown in the innovaphone license certificate.

[[Image:Created_activations.jpg|center|thumb|200px|created_activations.jpg/|created_activations.jpg/]]

You have to select an activation key in the activation key list to update or delete it.

Updating and deleting a key is only possible, if this key is not assigned.

====Update====
Add more licenses to this key or change its comment, order number and order reference. 
You can also remove licenses by entering e.g. -2, if you want to remove 2 licenses from the key.

[[Image:Own activations update.jpg|center|thumb|200px|own_activations_update.jpg/|own_activations_update.jpg/]]

====Delete====
Delete this key. Its licenses will go back into the balance of the currently selected project.

===Devices===
To view your devices you first have to click on the "Show" button. You can leave the filter field empty if you want to view all your devices.

[[Image:Devices_page.jpg|center|thumb|200px|devices_page.jpg/|devices_page.jpg/]]

Red marked device names are devices, which are currently in RMA.

MAC addresses of RMA devices do not longer start with 01-...

====List====
A List of your devices in the currently selected project. 
You can deselect the current project/device to list all your devices.

Select a certain device from the device list, to manage its properties, licenses etc.

Actions on multiple devices:
* Move: move several devices into another project at once (see [[#Move device|Move Device]])
* Remove: remove several devices at once (see [[#Remove|Remove]])

=====Add=====
Follow the "Add new devices" link on the devices page.

There you have a few options:
* You can add a single new device
* You can add devices according to a mac address range (e.g. from 00-90-33-08-20-00 to 00-90-33-08-22-00), maximum 50 at once
* You can add devices by uploading a text file with mac addresses like this (maximum 50 at once, each line one mac):

00-90-33-08-20-20
00-90-33-08-20-21
00-90-33-08-20-22
00-90-33-24-20-20

* You can add devices according to your received order number. Just enter you order number and you will get a list of all devices bount to this number.

Note: MAC addresses can be always given like this:
* 00-90-33-xx-xx-xx
* 00:90:33:xx:xx:xx
* 009033xxxxxx
* xxxxxx (00-90-33- will then be added automatically)

There might be errors, if you try to add a device. They are explained [[#Image explanation|here]].

As the device warranty will be handled by licenses now, you can also add telephone devices
to your projects.

=====Add warranty extensions=====

Here you can add warranty extension licenses for all devices in the currently selected project. 
You'll get a list of all devices with the corresponding license type(s) and you can specify the years for each device (or for all devices by entering the number in the list header). 
After confirming your selection, you'll get an overview of all needed licenses, which you have to confirm too.

=====Check licence, SSA and warranty status of a device=====
Here you can list licenses with ssa and the warranty end date of a device, which is not in one of your projects. 
For this option to work, you have to link your innovaphone customer ID (5 digits) to your my.innovaphone company. (As the warranty is also the one we grant to our distributors, we don't want to get an end customer confused.)

=====Download devices of an order as CSV=====
Enter an order number to retrieve all devices for this order in a CSV file.

=====Download devices of an order as PDF with barcodes=====
Enter an order number to retrieve all devices for this order in a PDF file with a barcode for each MAC address. 
Der Barcode ist vom Typ C128B.

====Properties====

Change the name and comment of a device.
You can only change the name, if it's no MAC or IPEI.
 
Here you have also the possibility, to directly request RMA for this device with prefilled values.

====Licenses====
Here you can add, download or move licenses.

=====Add licenses from balance=====
To create new licenses for a device, you have to add this device first on the devices page and then select a version of the license
and whether you want to summate the current licencing. If you select current licenses, then older licenses for example V6 or V7 licenses will also be counted as V8 licenses in the next overview. This is necessary if you want to license a V6 unit with V8 licenses, but still want to use it as V6.
After that click "Next".
On the next page you will see a list of all available license types, which depends on your current available license types, of the selected license version and the device type (IP6000, IP800 e.g.):
[[Image:licenses.jpg|center|thumb|200px|licenses.jpg/|licenses.jpg/]]
 
If your project has a SSA end date, which is not yet over, you'll have the possibility to set SSA for the new licenses to this SSA end date or you can optionally change this date to another one for the new licenses.
 
You see the available project balance, the balance over all projects (excluding external projects), the currently installed licenses and the maximum amount for this device type. You can now enter the value of the new license.
Base/Upgrade licenses can be selected via dropdown box.
'''Voicemail and Standby lics must always have the same amount as the selected PBX-PBX... license!
The maximum amount of PBX-Registration licenses equals the amount of the selected PBX-PBX... license!'''

The whished overall amount of pbx version 8 and above licenses can be specified here and the concrete amount of license sub types will be requested on the next page.

You can preview the SSC calculation of the wished licenses without having them in your balance.

[[Image:licenses2.jpg|center|thumb|200px|licenses2.jpg/|licenses2.jpg/]]

The best (cheapest) combination of each v8 pbx license type is already filled in, but you might change the amount of sub types if your does not fit and you do not want to purchase new activation keys for the sub types.

The column SSC/Unit is just shown if your project is currently under SSA and you have entered a SSA end date.

The SSC multiplicator is the value, which you have to multiplicate with each license unit to get
the corresponding SSC amount.
E.g. if you have 20 units of PBX-Port8*20 licenses with a SSC value of 54 and a multiplicator of
1.0000 (which equals to 365 days) you have to pay 20*54*1.0000 ~ 1080 SSCs.

 If you create licenses for an older version than the current version, you have to pay SSCs from the [[#Release dates|release date]] of the next version of the currently selected version twice. 
e.g.: you want to bind licenses for V6 with SSA, so you have to pay SSCs from the release date of V7
 You can also select for each license, if you want SSA for it or not. If not, no SSC is needed and no (new) SSA end date is set for this license. 

You can't change the SSA end date, if the project is under automatic SSA! You will receive an invoice for SSCs used for the new binding.

Now confirm your new selection. If you have not enough licenses in your current project, but there are still licenses in other projects, you will get a dropdown box with a list of all projects containing the needed licenses. You can now select all desired/needed projects and confirm your selection again.
The balance of all selected projects will then be decreased by the needed amount.
 
 
If your user account has the right to buy licenses on credit, just check the checkbox.
 
You may enter an order number, which you can use for your order, if you buy on credit.

=====Add licenses from free licenses=====

Here you can assign licenses, which you returned from other devices.
You will also have to select the desired version and will than get a list of fitting licenses according to the current device and selected version.

[[Image:licenses_free.jpg|center|thumb|200px|licenses_free.jpg/|licenses_free.jpg/]]

If a license is under SSA, the correct license type is shown in column 'License Type' besides the 'Original Type'.
On confirming the selection, a consistency check is done (e.g. only 4 Relay-PRI licenses on an IP6000).
Bind and SSA end date will be maintained for each license.

As external keys are also maintained, you can select e.g. an old Dect-Multicell-Ari license to have the same ARI on another IP1200.
 

If your project has a SSA end date, which is not yet over, you'll have the possibility to set SSA for the new licenses
to this SSA end date or you can optionally change this date to another one for the new licenses.
You will have to confirm this after your first license selection (this is the same calculation as [[#Software Service|here]]).

You can't change the SSA end date, if the project is under automatic SSA! You will receive an invoice for SSCs used for the binding.

=====Add V7 floating license (slave pbx)=====
Here you can add a V7 floating license for a slave pbx. A device with a floating license can't have V7 pbx licenses and a device with V7 pbx licenses can't have a floating license.

=====Delete V7 floating license=====
Here you can delete an already existing floating license, if you won't use it anymore.

=====Add warranty extension licenses=====
Extend your warranty by adding warranty extension licenses:

[[Image:add_warranty.jpg|center|thumb|200px|add_warranty.jpg/|add_warranty.jpg/]]

If you add the warranty extension immediately after the receipt of your device,
you can add the cheaper warranty extension licenses, otherwise you'll have to add
the more expensive ones.

You can extend the warranty for a maximum of four years.

=====Download licenses=====

[[Image:Device_download.jpg|center|thumb|200px|device_download.jpg/|device_download.jpg/]]

You will get a dropdown with all available versions. Versions are dependent of your device, your licenses and of the ssa of your licenses. 
'''From V9 on''', you just have one option, which will create a license file, which contains the licenses upgraded to the highest version of their type. 
You are able to download downgraded versions of your licenses. E.g. if you have only V8 licenses, you can download a V7 license file (same restrictions as below).

Downgrades or only possible down to version 6!

If you do not want to download licenses by version, you have to decide whether to download the licenses encrypted or not.
'''If you download the licenses unencrypted, you won't be able to return those licenses anymore.'''
So you won't be able to return licenses for devices with V5-V7 licenses, as licenses for these versions are not encrypted.
To return these licenses, you will have to upgrade to a new bootcode, which prevents firmware downgrades to versions below version 8. 
Encrypted licenses are stored in a xml file, which you can then upload on your V8 (or higher) device.

You can now also download licenses directly from by the web interface of a device.
You just have to enter your account data and start downloading the licenses from my.innovaphone.com
without having to download/upload a license file.

=====Download test licenses=====

[[Image:Device_download_test.jpg|center|thumb|200px|device_download_test.jpg/|device_download_test.jpg/]]

You can also download test licenses if you want to run tests. You will be asked, which version you want to use, whether the device is used as slave and if not used as slave, how many pbx licenses you want to use.

'''Important: Since V11, trial licenses are valid for 3 months and can be released once for a dedicated device. After expiration of those 3 months no further trial license creation for this device is possible.'''

V5 does '''not''' support test licenses!

=====Download App development license=====
If you're an App developer, you have the possibility, to generate a real license for you Apps which will contain your manufacturer prefix. 
The manufacturer prefix has to deposited at your my.innovaphone company by innovaphone before you can use this feature.

You can just have up to '''three''' different devices per company for which you can create such licenses!
These licenses aren't allowed for production usage!

You see your already used MAC addresses on this page too if you already created such licenses before.

=====Move licenses to another device=====
If you have the needed account rights or the device is already in RMA, you can move licenses to another device. After moving licenses, the former device will be marked as a RMA device.

You can just move licenses to devices without licenses!

=====Mix of rental and purchased licenses=====
From '''13r2 SR12''' onwards you can mix rental and purchased licenses. 
A device with rental licenses will be always inside a rental project (you recognize such a project by it's starting and ending '''$''' in the name). 
You can now add licenses from the balance to a device in such a rental project. 
 
If you invalidate lifetime licenses on such a device, just purchased licenses are returned. Rental licenses stay bound until you remove them inside your Devices App! (under rental menu)
Inside my.innovaphone you will always see both rental and purchased licenses. Inside the Devices App, you will just see the rental licenses. 
 
You must download and/or install the purchased licenses as usual. 
 
A 13r1 PBX or a PBX with an older SR will just recognize rented licenses!

If your PBX is already inside a non rental project, it will be automatically added to a rental project if you add rental licenses. You then may have the device in two different projects (one rental, one normal), which is no issue.

====Move device====
Here you can move the current device or the selected devices to another project. 
If you select a SSA project, you can change the SSA end date for the move process. 

If the other project is under SSA, you will first see a SSC calculation, which you have to confirm,
as the SSA date for each SSA license will be extended until the given SSA end date
(this is the same calculation as adding SSA to an already existing project, see [[#Software Service|here]]).

You can't change the SSA end date, if the other project is under automatic SSA! You will receive an invoice for SSCs used for the move.

====Invalidation====
====Returning of licenses====

By the invalidation, licenses are returned to the free balance of the project to which the device belongs in the Portal my.innovaphone. 
You can then bind the licenses from the free balance to another device.

=====Requirements=====
* V8 or higher
* access to the webinterface
* a device certificate
* my.innovaphone login credentials
* '''no IPVA device'''
* no 'In House' licenses

=====Informations=====

You can invalidate V8 (or higher) licenses by uploading the XML file, you got from your device or by returning your licenses over the web interface of your device ([[Reference8:Configuration/General/License]]), in order to return [[Reference8:Licenses#Gateway Licenses|PBX licenses]] back to the free balance.

V7 licenses can be just returned, if you agree, that you won't be able to downgrade below V8 anymore. You will need a new bootcode, to use this function. '''You need a V8 firmware or higher for invalidation.'''

If your device has access to my.innovaphone.com, you can also invalidate licenses directly
from the web interface of the device.

[[Reference8:Licenses#Gateway Licenses|gateway licenses]] and warranty extensions won't be returned to the balance and remain to be assigned to the device!

The licenses needn't be present on the local device to perform the invalidation!

SSA it's bound to the license and it's not lost when performing invalidation.

=====Process=====

Steps to invalidate licenses, if your device has internet connectivity:
# on the web interface of the device go to General->License and follow the my.innovaphone link
# enter your my.innovaphone account, the device must be in one of your projects
# click Invalidate
# click Transfer (this might fail, if NTP or DNS is not configured properly or device certificate is not installed)
# reset if asked for

Steps to invalidate licenses, if your device has no internet connectivity:
# on the web interface of the device go to General->License and follow the my.innovaphone link
# click Invalidate
# click Backup and upload this file on my.innovaphone [[#Upload the invalidation document to return licenses|here]] (Licenses->Devices (select the corresponding device)->Invalidation)
# you'll get a confirmation file after uploading the saved file
# upload this on the device (under Step1)
# reset if asked for

"Your IP800 does not have a device certificate on it." - In this case you need to download a hardware certification,
please contact the innovaphone [mailto:license@innovaphone.com license].

=====Download confirmation file=====
If you created a new certificate or you invalidated your licenses, you can later download the confirmation file, which you have to upload on the box.

=====Request certificate=====
If you have the needed rights, you can request a new device certificate for your device.

=====Upload the invalidation document to return licenses=====
Licenses->Devices (select the corresponding device)->Invalidation:

Upload the invalidation document, which you got from the website of the device to return the licenses of this device.

After uploading you'll get a confirmation file, which you have to upload on your device.

====Remove====
You can always remove devices from a project. If they have licenses, these won't be deleted, so you might add the device to another project again.

===History===
[[Image:history.jpg|center|thumb|200px|history.jpg/|history.jpg/]]
You can view your history for several contexts:
* Company: history of all actions in your company
* User: history of all actions of the selected user
* Device: history of all actions for the selected device

Each context applies to the currently selected project.
If you deselect the current project, you will see the history over all projects.

You can select to view the history of the last day, week, month, year or from always. Collecting data might take a while...

===Company===
Manage users SSA expiry email flag, import other companies or add your companies innovaphone ID.

====Users====

You can just edit the SSA expiry email flag here. The other user settings moved to the [[#Authorized Persons| Authorized persons tab]].

====Join (admin only)====
As admin you can also join another company into your company by entering an admin account of this company. This might be usefull if one user of your company has accidentally created an own company. 
Everything like projects, users, devices, balance, activations etc. will be imported! 
You also have to enter the company id of the company, which is to be imported. You can find this company under Licenses->Company and the company tab.

This is not available for non company admin users.

The joined company will be deleted afterwards!

====Company====

You can check the '''Device SSA''' checkbox, if you want to receive SSA expiry reminder mails for each device independent of the projects SSA end date.
These mails will be send weekly seven weeks before the SSA for a license a the device expires.
 
 
You can also enter additional email addresses, which should receive SSA emails.
 
You can define a global '''end user expiry mail text''' here, which will be sent to end users, if end users are configured in a [[#SSA Expiry Mail| project]]. This text can be overridden by a text in a project under [[#SSA Expiry Mail| SSA Expiry Mail]].

==RMA==
Here you can see all your RMA devices, which arrived innovaphone already. The licenses of this macadresses are moveable.
[[Image:rma.jpg|center|thumb|200px|rma.jpg/|rma.jpg/]]
 
If you want to request RMA for a certain device, go to the device properties and follow the "Request RMA" link.

==Support==
===Mantis===
Here you'll get a list of all open cases and [[Understanding the innovaphone trouble ticket status page#Information available| additional info regarding their state]] in our ticket system. This list is composed of all tickets assigned to email addresses of your my.innovaphone users in your company. 
Often used functions:
* You can click on the ticket number ("ID" column) to open an email prepared with the right emailadress and subject to address this case.
* You can click on the ''History'' link to get an overview of the already made communication with our support/presales-team.
* Another important new function is the option to upload larger files to your support/presales tickets using the ''Fileupload'' column.

===Announcements===
You can convert audio files into G.7xx files which you can use as announcements. 
 
;Supported input formats:
* mp3
* wav
* ogg
* flac
* ...

;Generated output formats:
* G.711u
* G.711a
* G.729
* G.723
* G.722

==Image explanation==

===Errors===

====Already In Company====
[[Image:Icon_in_company_inno_01.png|icon_in_company_inno_01.png/|icon_in_company_inno_01.png/]]
* This device already exists in your company and can't be added/imported.
If you want to import this device anyway, you first have to delete your current device from its project.

====Already Imported====
[[Image:Icon_imported_inno_01.png|icon_imported_inno_01.png/|icon_imported_inno_01.png/]]
* This device has been already imported.
You can't import it again.

====Not Found====
[[Image:Icon_not_found_inno_01.png|icon_not_found_inno_01.png/|icon_not_found_inno_01.png/]]
* This device was not found in the my innovaphone database.
This should never happen, but if, contact the administrator.

====IPVA MAC exists====
[[Image:Icon_ip_va_exists_inno_01.png|icon_ip_va_exists_inno_01.png/|icon_ip_va_exists_inno_01.png/]]
* An IPVA MAC address must be unique and can be assigned to just one company. You tried to add an already existing IPVA MAC.
Please assign a new one to your IPVA. For further details, see [[Reference13r2:Concept_Innovaphone_Virtual_Appliance#License_Configuration]].

my.innovaphone supports the following MAC address ranges:
* 00-50-56-...
* 00-15-5d-...
* 00-03-ff-...
* 00-0d-3a-...
* 00-12-5a-...
* 00-17-fa-...
* 00-50-f2-...
* 00-1d-d8-...
* 00-05-69-...
* 00-1c-14-...
* 00-0c-29-...
* 00-1d-db-...
* 5a-ad-1d-...
* 48-e9-ca-...
* bc-24-...
* e2-... ''this is an autogenerated MAC address of innovaphone cloud containers''

===Warnings===

====Several Companies====
[[Image:Icon_several_companies_inno_01.png|icon_several_companies_inno_01.png/|icon_several_companies_inno_01.png/]]
* This device is already in another company.
This means, that either you do not have the physical device or it once belonged another company.
You can still import/add this device and you will have access to all of its current licenses.

====Several Users====
[[Image:Icon several users inno 01.png|icon_several_users_inno_01.png/|icon_several_users_inno_01.png/]]
* This device has licenses from several users of the old license manager.
This means, that you are not neccessarily the user, who physically owns this device. If you do not own it, do not import it.

===Misc===
====No downgrade====
[[Image:no_downgrade.png|no_downgrade.png/|no_downgrade.png/]]
* Licenses, which have been downloaded for V5/V6/V7, were returned from this device, so no downgrade to these versions is allowed any more.



==Release dates==
V5: January 1st 2003 
V6: November 2nd 2006 
V7: November 14th 2008 
V8: December 7th 2009 
V9: April 26th 2011 
V10: July 8th 2013 
V11: February 9th 2015 
V12: July 11th 2016 
V13: May 13th 2019 
V14: December 20th 2023

V15: March 25th 2025 



==External interface==

There is an external interface, which you can use to control some functionality without a login to the my.innovaphone web site. 
You can use the interface with an '''HTTP GET''' request to the following URL: 
 
'''<code>https://my.innovaphone.com/interface.php</code>'''

Configure a trust value and a URL (can be a dummy URL if not used otherwise) unter Licenses -> Project -> Properties and tick "Configure Update-URL"

===General parameters for all commands===
:;cmd: the wished command
:;email: the email address of a user who is registered in my.innovaphone
:;project_id: the project ID of the project where the user has access to (you can find the project ID under [[#Properties| Licenses->Projects->Properties]])
:;hash: an SHA256 hash value which is computed over all GET parameters but the hash parameter itself plus the '''trust''' value of the project (see [[#Properties|Reference:My_Innovaphone#Properties]])
:;hash: the values of the GET parameters have to be URL encoded before calculation of the hash

;Example: URL <code>https://my.innovaphone.com/interface.php?cmd=addDevice&email=user@example.com&project_id=123456&serial=00-90-33-01-02-03&hash=b62f7948d6383cc365592ed289b6173cd35229cadc347847b953f78c8880d5b9</code>
:;project trust value: 1234567890abcdef
:;the data of the SHA256 hash: ?cmd=addDevice&email=user%40example.com&project_id=123456&serial=00-90-33-01-02-03&trust=1234567890abcdef
:;example PHP function call to generate the hash: hash("sha256", "?cmd=addDevice&email=user%40example.com&project_id=123456&serial=00-90-33-01-02-03&trust=1234567890abcdef");
:;with the current values, the function should return: b62f7948d6383cc365592ed289b6173cd35229cadc347847b953f78c8880d5b9

===Add a device to a project===
;HTTP GET parameters:
:;general parameters
:;cmd: '''addDevice'''
:;serial: the serial number of the device, e.g. 00-90-33-01-02-03
:;[device_desc]: optional, a description for the new device

;Return value: a JSON object is returned
:;success: boolean, either '''true''' or '''false'''
:;error: string, a string with an error. Just existent if success is false
:;example success: <syntaxhighlight lang="javascript">{ "success":true }</syntaxhighlight>
:;example error: <syntaxhighlight lang="javascript">{ "success":false, "error":"the project with ID 123456 doesn't exist" }</syntaxhighlight>

===Remove a device from a project===
;HTTP GET parameters:
:;general parameters
:;cmd: '''delDevice'''
:;serial: the serial number of the device, e.g. 00-90-33-01-02-03

;Return value: a JSON object is returned
:;success: boolean, either '''true''' or '''false'''
:;error: string, a string with an error. Just existent if success is false
:;example success: <syntaxhighlight lang="javascript">{ "success":true }</syntaxhighlight>
:;example error: <syntaxhighlight lang="javascript">{ "success":false, "error":"the project with ID 123456 doesn't exist" }</syntaxhighlight>

===Get the warranty of a device===
;HTTP GET parameters:
:;general parameters
:;cmd: '''getWarranty'''
:;serial: the serial number of the device, e.g. 00-90-33-01-02-03

;Return value: a JSON object is returned
:;success: boolean, either '''true''' or '''false'''
:;error: string, a string with an error. Just existent if success is false
:;warranty: a unix timestamp in seconds since 1970 (timezone Europe/Berlin), e.g. '''1448492400'''
:;warrantyStr: a string like '''"2015-11-26 00:00:00"'''

===Create a new project===
;HTTP GET parameters:
:;general parameters: you must use the project_id and trust value of an already existing project!
:;cmd: '''createProject'''
:;project_name: the name of the new project
:;[project_desc]: optional, a description for the new project
:;[update_url]: optional, an update URL for the project (do not forget to URL encode the value inside your HTTP GET request!)
:;[ssa_due_date]: optional, a unix timestamp in seconds since 1970 (timezone Europe/Berlin), e.g. '''1448492400'''

;Return value: a JSON object is returned
:;success: boolean, either '''true''' or '''false'''
:;error: string, a string with an error. Just existent if success is false
:;projectId: the project id of the created project

The newly created project is created with the same trust value which was used for the creation request. This allows you to directly use the API with the new project.

==Known Issues==
===Smaller issues===
* Devices where imported into a project with SSA. If this happened to you, please move the corresponding devices into a project '''without''' SSA and back into the project '''with''' SSA to extend/add SSA for the licenses until the SSA end date.
* IE7 moves a list under the menu, when a list becomes to wide
===Licenses don't work on a device, where an invalidation has been done===
A possible reason here is, that the invalidation process hasn't been completed.
To resolve this issue, follow these steps:

* Download the Confirmation File (Certificate) from http://my.innovaphone.com under [[#Invalidation|Invalidation]] after selecting the project and the device
* Open [[Reference9:General/License/my.innovaphone|General->License->my.innovaphone.com]] on your device
* Click on "Invalidate" (no my.innovaphone credentials needed)
* Upload the previously downloaded confirmation file newcert-00-90-33-xx-xx-xx.xml as "Confirmation file"
* Reset the box
* Reupload the licenses

===Internet Explorer doesn't work===
Yes, that's correct. Please use an up to date version of Chrome, Firefox or Edge!

Reference16r1:Concept innovaphone App Platform Container

2025-07-16T06:52:14Z

Dde: /* Environment Variables (ENVs) */

{{FIXME|reason=Below described feature is experimental and not officially supported for use in productive environments.}}
The innovaphone App Platform Docker container provides a myApps App Platform instance that includes the AP Manager, Webserver and PostgreSQL. This container offers a ready-to-use environment for myApps applications and the innovaphone PBX.

==Image Information==

This chapter provides details about the Docker image used for the innovaphone App Platform.

===Repository Details===

;Repository Host : docker.innovaphone.com
;Image Name : cloud/kubernetes/innovaphone-platform-instance

docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

===Tagging and Versioning===
The image is usually tagged with the build number according to innovaphone software releases:

;Latest Tag : Use the latest tag for pulling the most recent service release.

;Release Build Number : For production or version-specific deployments, use a specific build number as the tag (e.g., 130006).

Example:
docker pull docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

===Supported Architecture===
This Docker image supports the <code>linux/amd64</code> architecture.

===Image Reference===
An example of a full image reference using a specific release build number would be:
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

==Ports==
This chapter outlines the various ports exposed by the Docker container. The webserver ports are available immediately upon container startup, after start of the AP Manager and the Webserver, while the additional application ports become active after the app installation. In most cases, a one-to-one mapping is used, meaning the container port is mapped directly to the same host port unless otherwise specified.

===Webserver Ports===
;HTTP:
Container Port: 8080
Description: Used for accessing the built-in webserver immediately upon container startup.

;HTTPS:
Container Port: 8082
Description: Used for accessing the built-in webserver immediately upon container startup.

=== Additional Application Ports===
Following additional container ports are avilable depending on installed and configured applications:
;H323/TLS : 1300
;SIP : 5060
;SIPS : 5061
;LDAPS : 1636
;SMTP : 8025
;SMTPS : 8587
'''Additional hint for Portmapping'''<syntaxhighlight lang="yaml" line="1">
docker run -d \
--name=innovaphone \
--restart unless-stopped \
-p 9090:8080 \ #Container Host Port (external) 9090:8080 Container Port
-p 9091:8082 \
-p 5060:5060 \
-p 5061:5061 \
-p 1300:1300 \
-p 1636:1636 \
-p 8025:8025 \
-p 8587:8587 \
-v /path/of/data/innovaphone:/mnt/data \ #in this path you will find Apps, DBs & Logs
#this path musst be used for backups!!
-e WEBSERVERPORTHTTP=8080 \
-e WEBSERVERPORTHTTPS=8082 \
-e LOG_FLAGS=7 \
-e LOG_SIZE=1048576 \
-e DNSIPV4=8.8.8.8 \
-e LIMIT_RAM=512 \ #Ram limit in MB
-e LIMIT_DISK=10 \ #disk size in GB
-e TZ=Europe/Berlin \
docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

</syntaxhighlight>

==Environment Variables (ENVs)==
This chapter outlines the key environment variables used to configure the behavior of the innovaphone App Platform Docker container. These variables allow you to customize logging, port settings, resource limits, and more during startup and runtime.

;LOG_FLAGS : Defines the integer representation for the trace flags of the AP Manager, according flags activated under the AP Manager / Diagnostics. See browser console message on Save button press (e.g. "logFlags":1 , if the "App" flag is activated).
LOG_FLAGS=7
;LOG_SIZE : Specifies the maximum size in bytes for logs before rotation or management actions occur. Default: 5242880.
LOG_SIZE=1048576
;WEBSERVERPORTHTTP : Sets the in-container HTTP port for the webserver. Default: 8080.
WEBSERVERPORTHTTP=8080
;WEBSERVERPORTHTTPS : Sets the in-container HTTPS port for the webserver. Default: 8082.
WEBSERVERPORTHTTPS=8443
;DNSIPV4 : Specifies the in-container IPv4 address for DNS resolution. Overrides the deafult container runtime DNS server.
DNSIPV4=8.8.8.8
;LIMIT_RAM : Sets the RAM limit for the container, in MB, controlling how much memory it may consume. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_RAM=512
;LIMIT_DISK : Defines the disk space limit in GB for the container to manage storage consumption. Used by AP Manager to stop the app instances on overconsumption.
LIMIT_DISK=10
;MANAGER_DB_HOST : defines an external database host for the database of the App Platform Manager
If you hand database settings, the container will work without the local database server and doesn't need any storage at all (under development).
MANAGER_DB_HOST=172.16.14.35:5432 (port is optional)
;MANAGER_DB_NAME : the external database name
MANAGER_DB_NAME=databasename
;MANAGER_DB_USER : the external database user who has access
MANAGER_DB_USER=databaseuser
;MANAGER_DB_PASSWORD : the password of the user
MANAGER_DB_PASSWORD=o1kk2hj312k3
;DB_PROVISIONER_URL : a websocket URL to an external DBProvisioner App which is used to provide databases
DB_PROVISIONER_URL=wss://domain.com/domain.com/dbprovisioner

==Volumes and Mounts==
This container uses a dedicated internal mount path for the persistent data management across container restarts and updates.

===Internal Data Volume===
;Mount Path : <code>/mnt/data</code>
;Contents:
*Apps: Installed application binaries.
*Databases: PostgreSQL files.
*Logging: Log files for system and application events.

===Mounting===
To ensure that your data is preserved, map a host directory or Docker named volume to the container's /mnt/data path when running the container.
For example:
docker run -d -v /path/on/host:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:130006

This setup guarantees that your apps, associated data, databases, and logs persist independently of the container lifecycle.

==Entrypoint==
The container uses a fixed entrypoint:
ENTRYPOINT ["/entrypoint.sh"]

This script prepares the container and starts the AP Manager executable.

==Logging and Monitoring==
The log of the entrypoint.sh and of the AP manager is avilable as conatiner output. The installed applications store the ir log files under <code>/mnt/data/var/log/apps/</code>.

==Usage Example==
sudo docker run -d --restart unless-stopped --name innovaphoneAP -p 9090:8080 -p 9091:8082 -e WEBSERVERPORTHTTP=8080 -e WEBSERVERPORTHTTPS=8082 -v $(pwd)/myapps/:/mnt/data docker.innovaphone.com/cloud/kubernetes/innovaphone-platform-instance:latest

This command runs the container in detached mode with automatic restart. It names the container innovaphoneAP, maps host ports 9090 and 9091 to the container's HTTP and HTTPS ports, sets the webserver port environment variables, mounts a host directory to /mnt/data, and starts the AP Manager. After container start up the AP manager web UI is accessible via <code>http://localhost:9090</code> or <code>https://localhost:9091</code>.

Reference15r1:Concept App Service Devices

2025-07-04T12:11:33Z

Dde: /* Sample phoneplatform.json */

[[Category:Concept|Apps]]
The App Service Devices is an App Service which can be installed on an innovaphone App Platform. It is used to administrate the innovaphone devices which belong to the whole installation.
== Applies To ==

* innovaphone PBX from version 13r1

== Apps ==

=== Devices App (innovaphone-devices) ===
This is the standard UI App for Devices.

Parameters:

;Websocket: to publish the com.innovaphone.devicesui-API, which can be used to link directly to devices (which is done e.g. inside the Events app)

=== Devices API (innovaphone-devices-api) ===
This is a hidden App, which provides the Devices API (com.innovaphone.devices). This API can be used to find and communicate with devices which are registered to the Devices App.

Additionally it acts as a provider of the Search API (com.innovaphone.search). So you can find devices and domains in other apps like the Search App.

Parameters:

;Hidden: DevicesApi must be a hidden App
;Websocket: to get the URL of the Devices App itself which is used for provisioning

== PBX Manager Plugins ==

=== Devices ===

With the Devices plugin App objects can be created, edited and deleted for Devices and the Devices API on the PBX.

== Concepts ==
All innovaphone hard phones and gateways starting from version 13r1 can establish a registration inside the Devices App and therefor administrative tasks can be performed through the App.

=== Domains ===

In a hosted environment, it might be needed to add multiple domains to the Devices App. 
After the initial installation of Devices through Install, you have administrative rights and can add more domains.

==== Administrative rights ====
You have administrative rights if the configured PBX App object for Devices uses the password of the instance which is configured in the Manager App and the PBX uses the same domain as this instance.

==== Domain local rights ====
You have just rights to a certain domain if the configured PBX App object for Devices uses the domain password which can be configured in Devices for each domain and the PBX uses the same domain name as configured in Devices.

==== Assign rights to other domains ====
Domains can gain access to other domains by configuring these access rights in the Devices App.

==== Deploy passwords and access rights ====
During install, a domain is created inside the Devices App. There is a checkmark Deploy the domain password on all devices which is set by default and which is the same as the administrative password.
If you change the domain password, all passwords on all administrative devices and app platforms which are connected to this domain will be also changed. 
Since 13r2sr25/13r3sr7/14rx: devices which are auto provisioned or provisioned through the Profile/Users Admin App will get a random password instead of the domain password.
If you add a phone device manually to a domain inside the Devices App, this phone device will also get a random password. Other device types added manually or devices added with a provisioning code which has been created within the Devices App directly, will get the domain password instead. 
 
This will also set the manager password and the SSH passwords of App Platforms. 
 
The clear text random passwords can be requested and viewed in the settings of a device in the Devices App.

Attention: If you untick the '''Deploy administrative devices passwords''' checkmark, the password won't be deployed anymore, but also not reconfigured to the default password!

Attention: After each reconnect of a client, the password will be deployed again.
This means, if the checkmark is set and you set another password somewhere else (e.g. under General::Admin),
this password will be just valid until the next reboot or reconnect to the Devices App!

;Create new random passwords
You can rollout new random passwords by unticking the '''Deploy administrative devices passwords''' checkmark and ticking it again. 

;Devices with multiple domains (Cloud)
In a hosted environment, you can use the Devices App with multiple domains. The corresponding instance of Devices has a configured domain and an instance password set inside the manager. 

The hosting PBX has a domain inside Devices with a specific password. 
If this domain name matches the instance domain of the Devices instance and the password matches either the instance password or the domain password, you will be logged in as admin and have access to all domains. 

Each newly created domain has its own password inside Devices. If you create an App Object inside a PBX with this domain and the password of this domain (inside Devices), you will just have access to this single domain. 

Devices also has the possibility to grant access to other domains for a specific domain.

=== Categories ===

There are two types of categories:
* provisioning category: used for device configurations and provisioning
* standard category: used for update/backup jobs and device management

Each device can have just a '''single''' provisioning category, as it receives it's configuration by all configured device configurations for this provisioning category.

In addition, a provisioning category, which is used inside an analogue phone/phone device configuration '''cannot''' be used to provision a gateway.

=== Device connections ===
The Devices registration is done through a websocket connection to the webserver of the App Platform and the Devices instance (standard HTTP/s port). 
The URL used can be configured manually under [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:General/Devices_Registration Devices Registration] or through a new provisioning mechanism. 
 
A binary protocol is used to transfer information between the device and the devices App. The MAC address is the unique key to identify a device. 
 
If a device is added to a domain in Devices, the device gets a unique random password. Without such a password, a device shows up as '''unassigned''' in the Devices app.
This is also the case after a long reset or when the device lost its configuration. 
 
In such a case, the device has to be manually added again to a domain or it has to be provisioned again.

If a device is not assigned to a domain or provisioning category, it won't receive any configurations.

==== Devices Registrations ====
See [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:General/Devices_Registration Devices Registration]

==== Second Devices Registration URL ====

The firmware has a second SYSCLIENT2 module, which can be configured to point to a different Devices instance and the AP Manager also has a second Devices Registration URL. 
 
If you use this configuration option, you should take care and consider:

* if the Devices domain from the second configuration provides a password for all devices, the password is ignored, as it would lead to inconsistend passwords otherwise (from 13r1 SR12 on)
* the Devices domain from the second configuration should not provide Devices Configurations or Update Jobs as these might collide with configurations from the first Devices instance!

Generally, only one of the two ''Devices'' App instances connected to the device must apply changes to the device.

We strongly discourage the usage of this second configuration option due to unexpected behaviour if incorrectly used!
Never use the second URL if you use software or hardware rental!

==== Device information ====

The following data is transferred:
* MAC address
* device type (e.g. IPVA, AppPlatform, IP112)
* IP addresses (IPv4, IPv6)
* version (not searchable)

You can also search for this data inside the devices tab in the App.


=== Provisioning ===
Devices can be added by provisioning (both phones and gateways).
The standard online provisioning looks like this:
* a user or administrator creates a provisioning code in the Devices or Users App (this stores the Devices URL on the provisioning server side)
* a device with 13r1 or newer is connected to the network after a long reset
* the provisioning code has to be entered within one hour (after one hour, the Update URL isn't polled anymore)
* the device sends this code to config.innovaphone.com and retrieves the Devices URL
* the device connects to the Devices URL and is added to the domain where the code has been created

There is also an [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Offline_Provisioning offline provisioning mode]. 
There is also an [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Provisioning#Automatic_provisioning automatic provisioning mode].

Note: provisioning is cancelled if the device already belongs to another domain in the same Devices instance! This prevents the unauthorized move of a device between different domains.

==== Devices Registration URL ====

The Devices Registration URL which is set through the provisioning process, always starts with '''wss'''. This is not dependent anymore on the App URL which is configured inside the PBX Devices App object.

=== Updates ===
The Devices App can be used to rollout updates. 

==== JSON files ====
The update files have to be acccessible on a webserver without authentication and four json files are used:
* firmware.json: innovaphone device firmware
* apps.json: Apps for the App Platform
* software.json: contains software for DECT handsets
** just IP64 and IP65 are used and supported
* phoneplatform.json: contains the phone platform image for e.g. the IP270

You can either use the standard innovaphone App Store for these files or your own local webserver. 

==== Update jobs ====
You can configure several update jobs with different categories to organize your updates. 
Update jobs are always sequentially processed and inside one update job, just '''20''' devices are updated at the same time.

==== Device update check after the update job has been already executed====
If a device goes online, the newest suitable update job is searched for this device (depending on the categories). 
If an update job is found, the update is just performed, if there has been '''no''' successfull update for this device in this job before and the version does not match (simply string compare).

====Update errors====
If an update fails, the Devices App shows an error. You may have to enable further tracing on the updated device itself to find out the reason of the failure. 
 
* on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0 module and take a look at the events which may already tell you the reason
* on an App Platform, enable the App and HTTP Client trace flag on the manager

An update job is retried '''two''' times if updates inside this job failed. The retry is done '''ten''' minutes after the update job finished previously.

====innovaphone myApps====
The path to the App Store and the used innovaphone myApps version is updated to the version of the gateway on gateways with an enabled PBX after a successfull update. 
This configuration can be found [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:PBX/Config/myApps here]

Inside the configuration on an update job, the flag "Do not update myApps launcher software" disables the update of the innovaphone myApps version inside PBXes.

====DECT handsets====
If you check the update DECT handsets checkmark, all DECT devices will be configured to rollout updates to DECT handsets. 
See [[{{NAMESPACE}}:Concept_App_Service_Devices#Supported_DECT_handsets | Supported DECT handsets]].

The DECT handset firmware will be searched inside the configured software.json.

=== Backups ===
The Devices App can be used to backup the configuration and data of Apps and devices. 

====Webserver requirements====
Backups are stored on a webserver with or without Digest/Basic authentication and with the '''webdav PUT''' method.

====Backup jobs====
Backup jobs are executed sequentially. Inside one backup job, just '''20''' backups are performed at the same time.

====Phones or gateways====
The configuration file is stored. Therefor the Devices App tells the device to store the configuration with a !mod cmd UP0 /sync prot URL.

====Apps on an App Platform====
The databases of all existing instances and the manager are stored. 
Each installed App Service can have multiple instances and each App instance has its own database. 
A database contains '''both''' configuration and data of an App instance! 
The manager database contains the webserver certificate and further manager related configuration settings.

The Devices App establishes a websocket connection to the manager and tells the manager where to store the backups. 
The manager on the backuped App Platform itself performs the HTTP requests to store the files.

====Backup errors====
If a backup fails, the Devices App shows an error. You may have to enable further tracing on the backuped device itself to find out the reason of the failure.

* on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0
* on an App Platform, enable the App and HTTP Client trace flag on the manager

=== Restore ===
====Phones or gateways====
Just as always under [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Administration/Upload/Config Upload Config].

====Apps====
The App Service itself has to be installed on the App Platform prior restoring of a single instance. 
The restoring is done in the Manager App on the App Platform itself. 
The intance settings, the configuration and data are restored in a single process.

=== Device Configurations ===

You can define several device configurations. These configurations are either applied to all devices inside this domain or to selected categories. 
Configurations are applied on creation and on every reconnect of a matching device.

==== Transfer checkmarks ====

Some configuration options have a specific checkmark to enable the transfer of the option. 
 
* Checkmark disabled:
** configuration option field(s) are disabled
** option values are '''not''' transferred at all
* Checkmark enabled:
** configuration option field(s) are enabled
** option values are transferred, even if field values are empty

==== Expert configuration ====

The expert configuration can be used to configure different settings which are not available inside the other device configurations. 
You can use the standard syntax of an update server script (see [[ {{NAMESPACE}}:Concept_Update_Server | Concept Update Server ]] for a general overview and the section on [[Howto:PHP_based_Update_Server_V2#Hints_for_writing_your_update_snippets | Hints for writing your update snippets ]] (note that the remainder of this article relates to the now deprecated old mechanism, so please disregard the rest)). 
 
Some hints:
* the expert configuration is just executed once after a device restarted and on change of the expert configuration itself
* the expert configuration is executed after all other device configuration types, so that you can override changes
* to make configuration changes effective, you may also need to issue a final ''config write'', ''config activate'' and ''iresetn'' command (see the [[ {{NAMESPACE}}:Concept_Update_Server#Check_command | ''check'' command]] for details)
* some commands shouldn't be used inside the script:
** [[ {{NAMESPACE}}:Concept_Update_Server#Times_command |''times'']]: since the expert configuration is executed only once after a reboot of the device and when changes are made, it does not make sense to use the ''times'' command
** [[ {{NAMESPACE}}:Concept_Update_Server#Prot_command |''prot'']]|[[ {{NAMESPACE}}:Concept_Update_Server#Boot_command |''boot'']]: use an update job instead
** [[ {{NAMESPACE}}:Concept_Update_Server#Scfg_command |''scfg'']]: use a backup job instead
** [[Howto:PHP_based_Update_Server_V2#Using_vars_create|''vars create'']]: this cmd will always raise the ''reset needed condition'' and the aforementioned ''iresetn'' command would always execute therefore. As a result, the devices would enter a boot loop. Be sure to avoid this using an appropriate [[ {{NAMESPACE}}:Concept_Update_Server#Check_command |''check'' command ]] and update its ''<serial>'' properly whenever the expert configuration is changed

==== Certificates configuration ====
You can use this configuration to rollout certificates to the trust list of your devices. 

* Manual upload certificates.
* Configure up to five URLs which are polled every 24 hours. They must return files with PEM formatted public keys (one or more) which are then rolled out.
* Configure https://download.innovaphone.com/certificates/innovaphone.pem to always have the innovaphone public keys in your trust list (e.g. used for our push service).
* Configure https://download.innovaphone.com/certificates/ca.pem to always have the innovaphone Device Certification Authority certificates in your trust list.
* Configure https://download.innovaphone.com/certificates/ca-unverified.pem to always have the innovaphone Unverified Device Certification Authority certificates in your trust list.
** The Unverified CA is used for non hardware devices, e.g. IPVAs, which are not shipped with an official innovaphone Device Certification Authority certificate, as innovaphone has no control over the serial number here.

Using this configuration, the trust list can only be managed through ''Devices'' because it is cleared before each rollout.

==== DECT Handsets ====

This configuration can be used to configure specific options like language, voicemail number etc. for DECT handsets. 
 
* all DECT devices like IP1202, IP1203 etc. will receive this configuration (of course just if the configured categories match)
* Devices configures a URL like https://domain.com/domain.com/devices/parameters/id.xml on the specific DEVMANBW module.
* This file is then polled by the basestations and the read values are transfered to the DECT handsets.
* see [[{{NAMESPACE}}:IP1202/IP1203_DECT_System#Configuration_of_Handset_parameters]]

See [[{{NAMESPACE}}:Concept_App_Service_Devices#Supported_DECT_handsets | Supported DECT handsets]].

=== Software rental ===
Regarding the Software Rental program and the Payment Method, please refer to:
* [[{{NAMESPACE}}:Concept_Software_Rental|Concept Software Rental]]

Software rental can be done for innovaphone Cloud installations or for software, which operates on the customer premisis. This could eventually be customer owned hardware or a privat virtual machine, managed by the customer.

==== Hardware licenses ====
Hardware licenses have to be bound on the specific device in my.innovaphone itself and currently can't be handled within the Devices App itself. So you also need to download the licenses from my.innovaphone and upload them on the device with the already known methods.

===== Hardware licenses with software rental =====
If your device has software rental licenses, you can bind hardware licenses within my.innovaphone in the software rental project itself.

===== Hardware licenses without software rental =====
If your device does not have software rental licenses, you should bind hardware licenses in a separate non rental project in my.innovaphone.

==== innovaphone Cloud ====
Inside the innovaphone Cloud, you just have to upload your activation keys with iSCs to add licenses to one or more gateways. 

==== Email expiry notifications ====
You will receive an email notification if the rental of a project expires. This notification will be sent '''seven''' weeks before the expiry and then once a week until the rental expires. 
You can configure one or more email recipients in the domain settings. 
If no email address is configured, the email address of the logged in user account is used.

==== History ====
You can download the history in the Devices App. You'll get a CSV file (semicolon separated). The date and number format depends on the selected language in the UI. 
There is also an API available for automated downloas, which is described [[ {{NAMESPACE}}:Concept_App_Service_Devices#API_to_download_rental_history|here ]].

====Own installation====
Inside your own installation, you have to register a new my.innovaphone account or you can use an existing account inside the Devices App. 
One domain inside Devices belongs to one project inside your my.innovaphone company, so you can handle multiple domains with one my.innovaphone account.

====Technical aspects====
A new rental expiration date is calculated on each license or balance change in the domain. 
So after each change new licenses with a new date are transfered to the gateways and also stored in the Devices App itself. 
If the rental expires, the gateway reboots and the licenses are not available anymore. 
The licenses are also transfered after each reconnect of a gateway to the Devices App. 
 
For license and balance changes, the Devices App must be online and have access to my.innovaphone.com!

====Usage====
You have to add (use the + symbol) a PBX and select all licenses you want to rent. 
Use the '''apply''' button to really bind these licenses. Without usage of the apply button, you can just see a precalculation of the iSCs/month and the rental end date, but nothing is really charged from your balance.

===Change of IP address/DNS name in PBX object===
If the IP address or DNS name inside the PBX object of the Devices App changes, all currently connected clients get a new Devices Registration URL and also all clients, which connect afterwards with the old host name.

== Appendix ==
=== Sample firmware.json ===
<code type="javascript">
{
"devices": [
{ "id": "IP0010", "versions": [ "13r1" ] },
{ "id": "IP0011", "versions": [ "13r1" ] },
{ "id": "IP101", "versions": [ "13r1" ] },
{ "id": "IP102", "versions": [ "13r1" ] },
{ "id": "IP1060", "versions": [ "13r1" ] },
{ "id": "IP110", "versions": [ "13r1" ] },
{ "id": "IP110A", "versions": [ "13r1" ] },
{ "id": "IP111", "versions": [ "13r1" ] },
{ "id": "IP112", "versions": [ "13r1" ] },
{ "id": "IP1130", "versions": [ "13r1" ] },
{ "id": "IP1260", "versions": [ "13r1" ] },
{ "id": "IP150", "versions": [ "13r1" ] },
{ "id": "IP2000", "versions": [ "13r1" ] },
{ "id": "IP200A", "versions": [ "13r1" ] },
{ "id": "IP22", "versions": [ "13r1" ] },
{ "id": "IP222", "versions": [ "13r1" ] },
{ "id": "IP230", "versions": [ "13r1" ] },
{ "id": "IP232", "versions": [ "13r1" ] },
{ "id": "IP24", "versions": [ "13r1" ] },
{ "id": "IP240", "versions": [ "13r1" ] },
{ "id": "IP241", "versions": [ "13r1" ] },
{ "id": "IP29", "versions": [ "13r1" ] },
{ "id": "IP3010", "versions": [ "13r1" ] },
{ "id": "IP3011", "versions": [ "13r1" ] },
{ "id": "IP302", "versions": [ "13r1" ] },
{ "id": "IP305", "versions": [ "13r1" ] },
{ "id": "IP311", "versions": [ "13r1" ] },
{ "id": "IP411", "versions": [ "13r1" ] },
{ "id": "IP6000", "versions": [ "13r1" ] },
{ "id": "IP6010", "versions": [ "13r1" ] },
{ "id": "IP800", "versions": [ "13r1" ] },
{ "id": "IP810", "versions": [ "13r1" ] },
{ "id": "IP811", "versions": [ "13r1" ] },
{ "id": "IPVA", "versions": [ "13r1" ] }
],
"versions": [
{ "id": "13r1", "build": "131705", "text": "13r1 dvl [131705]", "wiki": "" }
]
}
</code>

=== Sample apps.json ===
<code type="javascript">
{
"apps": [
{
"id": "apidemo",
"folder": "apidemo",
"binary": "apidemo",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "Apidemo",
"description": "The Apidemo"
},
{
"id": "appstore",
"folder": "appstore",
"binary": "appstore",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "AppStore",
"description": "AppStore"
}
]
}
</code>

=== Sample software.json ===
<code type="javascript">
{
"software": [
{
"id": "myappsandroid",
"folder": "myappsandroid",
"binary": "myapps.apk",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "myApps Android",
"description": "myApps for Android"
},
{
"id": "myappswindows",
"folder": "myappswindows",
"binary": "myAppsSetup.msi",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "myApps Windows",
"description": "myApps for Windows"
}
]
}
</code>

=== Sample phoneplatform.json ===
<code type="javascript">
{
"phoneplatforms": [
{
"id": "arm64",
"text": "Phone Platform",
"file": "phone-platform.img",
"folder": "yocto2",
"version": "2063"
}
],
"devices": [
{
"id": "IP270",
"phoneplatforms": [
"arm64"
]
}
]
}
</code>

=== API to download rental history ===

You can download the history as a UTF-8 CSV file with simple '''HTTP GET''' requests with '''digest''' authentication. 
The CSV file uses the semicolon as delimiter. 
 
The URL to download the history is e.g.: 
'''<code>https://mydomain.com/mydomain.com/devices/csvapi?...</code>'''

You can find this path by editing the instance in the AP manager.
In the listed paths, you'll find something which ends with csvapi

In the innovaphone Cloud environment, the URL can be retrieved by taking a look at the Devices App object inside the cloud PBX and replacing the ending '''innovaphone-devices''' with '''csvapi''' inside the App URL, so it looks e.g. like this:

https://cloud-apps0.innovaphone.com/cloud.innovaphone.com/devices/csvapi

====CSV columns====
Most columns should be self explaining, but the column '''invoice reference''' refers to a value which you can configure manually in the domain settings in the Devices App!

====Digest authentication====
You can login with two different username/password combinations, while the domain is the digest username:

* If you use the domain and password of your Devices App instance inside the AP Manager, you have automatically access to all domains. 
* If you use the domain name of any domain as digest username and the configured domain password, you'll have access to this domain and all domains to which this domain has access to

====Query parameters====
The following query parameters can be used (don't forget to URL encode the parameter values, if neccessary!):
* all: if '''1''' or '''true''', the history is queried for all domains where the digest user has access to
* domain: required, if ''all'' is not set
* lang: the output language of the CSV file, which also controls date and number formats, e.g. '''en''', '''de''', ...
* tz: the timezone for dates, e.g. '''Europe/Berlin'''
* type: two types are available:
** '''history''': history which contains changes
** '''overview''': a monthly overview with the iSC costs at the first of the last months
* from: unix timestamp (UTC) in milliseconds, ignored for type=overview
* to: unix timestamp (UTC) in milliseconds, ignored for type=overview

====Example requests====
* <code>https://mydomain.com/mydomain.com/devices/csvapi?domain=mydomain.com&type=overview&lang=en&tz=Europe%2FBerlin</code>
* <code>https://mydomain.com/mydomain.com/devices/csvapi?domain=mydomain.com&type=history&lang=en&tz=Europe%2FBerlin&from=1601903431000&to=1601903385000</code>
* <code>https://mydomain.com/mydomain.com/devices/csvapi?all=1&type=overview&lang=en&tz=Europe%2FBerlin</code>

=== Supported DECT handsets ===

The following handsets are supported for update jobs and the DECT handsets configuration:

* IP64
* IP65
* D81
* D83

== Known issues ==

===SoftwarePhone===
The Devices App is not meant to be used with the windows SoftwarPhone standalone installation.

== Related Articles ==
* [[Howto:Software_Rental]]

Reference15r1:Concept App Service Devices

2025-07-04T12:11:19Z

Dde: /* Sample software.json */

[[Category:Concept|Apps]]
The App Service Devices is an App Service which can be installed on an innovaphone App Platform. It is used to administrate the innovaphone devices which belong to the whole installation.
== Applies To ==

* innovaphone PBX from version 13r1

== Apps ==

=== Devices App (innovaphone-devices) ===
This is the standard UI App for Devices.

Parameters:

;Websocket: to publish the com.innovaphone.devicesui-API, which can be used to link directly to devices (which is done e.g. inside the Events app)

=== Devices API (innovaphone-devices-api) ===
This is a hidden App, which provides the Devices API (com.innovaphone.devices). This API can be used to find and communicate with devices which are registered to the Devices App.

Additionally it acts as a provider of the Search API (com.innovaphone.search). So you can find devices and domains in other apps like the Search App.

Parameters:

;Hidden: DevicesApi must be a hidden App
;Websocket: to get the URL of the Devices App itself which is used for provisioning

== PBX Manager Plugins ==

=== Devices ===

With the Devices plugin App objects can be created, edited and deleted for Devices and the Devices API on the PBX.

== Concepts ==
All innovaphone hard phones and gateways starting from version 13r1 can establish a registration inside the Devices App and therefor administrative tasks can be performed through the App.

=== Domains ===

In a hosted environment, it might be needed to add multiple domains to the Devices App. 
After the initial installation of Devices through Install, you have administrative rights and can add more domains.

==== Administrative rights ====
You have administrative rights if the configured PBX App object for Devices uses the password of the instance which is configured in the Manager App and the PBX uses the same domain as this instance.

==== Domain local rights ====
You have just rights to a certain domain if the configured PBX App object for Devices uses the domain password which can be configured in Devices for each domain and the PBX uses the same domain name as configured in Devices.

==== Assign rights to other domains ====
Domains can gain access to other domains by configuring these access rights in the Devices App.

==== Deploy passwords and access rights ====
During install, a domain is created inside the Devices App. There is a checkmark Deploy the domain password on all devices which is set by default and which is the same as the administrative password.
If you change the domain password, all passwords on all administrative devices and app platforms which are connected to this domain will be also changed. 
Since 13r2sr25/13r3sr7/14rx: devices which are auto provisioned or provisioned through the Profile/Users Admin App will get a random password instead of the domain password.
If you add a phone device manually to a domain inside the Devices App, this phone device will also get a random password. Other device types added manually or devices added with a provisioning code which has been created within the Devices App directly, will get the domain password instead. 
 
This will also set the manager password and the SSH passwords of App Platforms. 
 
The clear text random passwords can be requested and viewed in the settings of a device in the Devices App.

Attention: If you untick the '''Deploy administrative devices passwords''' checkmark, the password won't be deployed anymore, but also not reconfigured to the default password!

Attention: After each reconnect of a client, the password will be deployed again.
This means, if the checkmark is set and you set another password somewhere else (e.g. under General::Admin),
this password will be just valid until the next reboot or reconnect to the Devices App!

;Create new random passwords
You can rollout new random passwords by unticking the '''Deploy administrative devices passwords''' checkmark and ticking it again. 

;Devices with multiple domains (Cloud)
In a hosted environment, you can use the Devices App with multiple domains. The corresponding instance of Devices has a configured domain and an instance password set inside the manager. 

The hosting PBX has a domain inside Devices with a specific password. 
If this domain name matches the instance domain of the Devices instance and the password matches either the instance password or the domain password, you will be logged in as admin and have access to all domains. 

Each newly created domain has its own password inside Devices. If you create an App Object inside a PBX with this domain and the password of this domain (inside Devices), you will just have access to this single domain. 

Devices also has the possibility to grant access to other domains for a specific domain.

=== Categories ===

There are two types of categories:
* provisioning category: used for device configurations and provisioning
* standard category: used for update/backup jobs and device management

Each device can have just a '''single''' provisioning category, as it receives it's configuration by all configured device configurations for this provisioning category.

In addition, a provisioning category, which is used inside an analogue phone/phone device configuration '''cannot''' be used to provision a gateway.

=== Device connections ===
The Devices registration is done through a websocket connection to the webserver of the App Platform and the Devices instance (standard HTTP/s port). 
The URL used can be configured manually under [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:General/Devices_Registration Devices Registration] or through a new provisioning mechanism. 
 
A binary protocol is used to transfer information between the device and the devices App. The MAC address is the unique key to identify a device. 
 
If a device is added to a domain in Devices, the device gets a unique random password. Without such a password, a device shows up as '''unassigned''' in the Devices app.
This is also the case after a long reset or when the device lost its configuration. 
 
In such a case, the device has to be manually added again to a domain or it has to be provisioned again.

If a device is not assigned to a domain or provisioning category, it won't receive any configurations.

==== Devices Registrations ====
See [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:General/Devices_Registration Devices Registration]

==== Second Devices Registration URL ====

The firmware has a second SYSCLIENT2 module, which can be configured to point to a different Devices instance and the AP Manager also has a second Devices Registration URL. 
 
If you use this configuration option, you should take care and consider:

* if the Devices domain from the second configuration provides a password for all devices, the password is ignored, as it would lead to inconsistend passwords otherwise (from 13r1 SR12 on)
* the Devices domain from the second configuration should not provide Devices Configurations or Update Jobs as these might collide with configurations from the first Devices instance!

Generally, only one of the two ''Devices'' App instances connected to the device must apply changes to the device.

We strongly discourage the usage of this second configuration option due to unexpected behaviour if incorrectly used!
Never use the second URL if you use software or hardware rental!

==== Device information ====

The following data is transferred:
* MAC address
* device type (e.g. IPVA, AppPlatform, IP112)
* IP addresses (IPv4, IPv6)
* version (not searchable)

You can also search for this data inside the devices tab in the App.


=== Provisioning ===
Devices can be added by provisioning (both phones and gateways).
The standard online provisioning looks like this:
* a user or administrator creates a provisioning code in the Devices or Users App (this stores the Devices URL on the provisioning server side)
* a device with 13r1 or newer is connected to the network after a long reset
* the provisioning code has to be entered within one hour (after one hour, the Update URL isn't polled anymore)
* the device sends this code to config.innovaphone.com and retrieves the Devices URL
* the device connects to the Devices URL and is added to the domain where the code has been created

There is also an [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Offline_Provisioning offline provisioning mode]. 
There is also an [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Provisioning#Automatic_provisioning automatic provisioning mode].

Note: provisioning is cancelled if the device already belongs to another domain in the same Devices instance! This prevents the unauthorized move of a device between different domains.

==== Devices Registration URL ====

The Devices Registration URL which is set through the provisioning process, always starts with '''wss'''. This is not dependent anymore on the App URL which is configured inside the PBX Devices App object.

=== Updates ===
The Devices App can be used to rollout updates. 

==== JSON files ====
The update files have to be acccessible on a webserver without authentication and four json files are used:
* firmware.json: innovaphone device firmware
* apps.json: Apps for the App Platform
* software.json: contains software for DECT handsets
** just IP64 and IP65 are used and supported
* phoneplatform.json: contains the phone platform image for e.g. the IP270

You can either use the standard innovaphone App Store for these files or your own local webserver. 

==== Update jobs ====
You can configure several update jobs with different categories to organize your updates. 
Update jobs are always sequentially processed and inside one update job, just '''20''' devices are updated at the same time.

==== Device update check after the update job has been already executed====
If a device goes online, the newest suitable update job is searched for this device (depending on the categories). 
If an update job is found, the update is just performed, if there has been '''no''' successfull update for this device in this job before and the version does not match (simply string compare).

====Update errors====
If an update fails, the Devices App shows an error. You may have to enable further tracing on the updated device itself to find out the reason of the failure. 
 
* on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0 module and take a look at the events which may already tell you the reason
* on an App Platform, enable the App and HTTP Client trace flag on the manager

An update job is retried '''two''' times if updates inside this job failed. The retry is done '''ten''' minutes after the update job finished previously.

====innovaphone myApps====
The path to the App Store and the used innovaphone myApps version is updated to the version of the gateway on gateways with an enabled PBX after a successfull update. 
This configuration can be found [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:PBX/Config/myApps here]

Inside the configuration on an update job, the flag "Do not update myApps launcher software" disables the update of the innovaphone myApps version inside PBXes.

====DECT handsets====
If you check the update DECT handsets checkmark, all DECT devices will be configured to rollout updates to DECT handsets. 
See [[{{NAMESPACE}}:Concept_App_Service_Devices#Supported_DECT_handsets | Supported DECT handsets]].

The DECT handset firmware will be searched inside the configured software.json.

=== Backups ===
The Devices App can be used to backup the configuration and data of Apps and devices. 

====Webserver requirements====
Backups are stored on a webserver with or without Digest/Basic authentication and with the '''webdav PUT''' method.

====Backup jobs====
Backup jobs are executed sequentially. Inside one backup job, just '''20''' backups are performed at the same time.

====Phones or gateways====
The configuration file is stored. Therefor the Devices App tells the device to store the configuration with a !mod cmd UP0 /sync prot URL.

====Apps on an App Platform====
The databases of all existing instances and the manager are stored. 
Each installed App Service can have multiple instances and each App instance has its own database. 
A database contains '''both''' configuration and data of an App instance! 
The manager database contains the webserver certificate and further manager related configuration settings.

The Devices App establishes a websocket connection to the manager and tells the manager where to store the backups. 
The manager on the backuped App Platform itself performs the HTTP requests to store the files.

====Backup errors====
If a backup fails, the Devices App shows an error. You may have to enable further tracing on the backuped device itself to find out the reason of the failure.

* on a gateway/phone add a trace flag to the UP1 and HTTPCLIENT0
* on an App Platform, enable the App and HTTP Client trace flag on the manager

=== Restore ===
====Phones or gateways====
Just as always under [http://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Administration/Upload/Config Upload Config].

====Apps====
The App Service itself has to be installed on the App Platform prior restoring of a single instance. 
The restoring is done in the Manager App on the App Platform itself. 
The intance settings, the configuration and data are restored in a single process.

=== Device Configurations ===

You can define several device configurations. These configurations are either applied to all devices inside this domain or to selected categories. 
Configurations are applied on creation and on every reconnect of a matching device.

==== Transfer checkmarks ====

Some configuration options have a specific checkmark to enable the transfer of the option. 
 
* Checkmark disabled:
** configuration option field(s) are disabled
** option values are '''not''' transferred at all
* Checkmark enabled:
** configuration option field(s) are enabled
** option values are transferred, even if field values are empty

==== Expert configuration ====

The expert configuration can be used to configure different settings which are not available inside the other device configurations. 
You can use the standard syntax of an update server script (see [[ {{NAMESPACE}}:Concept_Update_Server | Concept Update Server ]] for a general overview and the section on [[Howto:PHP_based_Update_Server_V2#Hints_for_writing_your_update_snippets | Hints for writing your update snippets ]] (note that the remainder of this article relates to the now deprecated old mechanism, so please disregard the rest)). 
 
Some hints:
* the expert configuration is just executed once after a device restarted and on change of the expert configuration itself
* the expert configuration is executed after all other device configuration types, so that you can override changes
* to make configuration changes effective, you may also need to issue a final ''config write'', ''config activate'' and ''iresetn'' command (see the [[ {{NAMESPACE}}:Concept_Update_Server#Check_command | ''check'' command]] for details)
* some commands shouldn't be used inside the script:
** [[ {{NAMESPACE}}:Concept_Update_Server#Times_command |''times'']]: since the expert configuration is executed only once after a reboot of the device and when changes are made, it does not make sense to use the ''times'' command
** [[ {{NAMESPACE}}:Concept_Update_Server#Prot_command |''prot'']]|[[ {{NAMESPACE}}:Concept_Update_Server#Boot_command |''boot'']]: use an update job instead
** [[ {{NAMESPACE}}:Concept_Update_Server#Scfg_command |''scfg'']]: use a backup job instead
** [[Howto:PHP_based_Update_Server_V2#Using_vars_create|''vars create'']]: this cmd will always raise the ''reset needed condition'' and the aforementioned ''iresetn'' command would always execute therefore. As a result, the devices would enter a boot loop. Be sure to avoid this using an appropriate [[ {{NAMESPACE}}:Concept_Update_Server#Check_command |''check'' command ]] and update its ''<serial>'' properly whenever the expert configuration is changed

==== Certificates configuration ====
You can use this configuration to rollout certificates to the trust list of your devices. 

* Manual upload certificates.
* Configure up to five URLs which are polled every 24 hours. They must return files with PEM formatted public keys (one or more) which are then rolled out.
* Configure https://download.innovaphone.com/certificates/innovaphone.pem to always have the innovaphone public keys in your trust list (e.g. used for our push service).
* Configure https://download.innovaphone.com/certificates/ca.pem to always have the innovaphone Device Certification Authority certificates in your trust list.
* Configure https://download.innovaphone.com/certificates/ca-unverified.pem to always have the innovaphone Unverified Device Certification Authority certificates in your trust list.
** The Unverified CA is used for non hardware devices, e.g. IPVAs, which are not shipped with an official innovaphone Device Certification Authority certificate, as innovaphone has no control over the serial number here.

Using this configuration, the trust list can only be managed through ''Devices'' because it is cleared before each rollout.

==== DECT Handsets ====

This configuration can be used to configure specific options like language, voicemail number etc. for DECT handsets. 
 
* all DECT devices like IP1202, IP1203 etc. will receive this configuration (of course just if the configured categories match)
* Devices configures a URL like https://domain.com/domain.com/devices/parameters/id.xml on the specific DEVMANBW module.
* This file is then polled by the basestations and the read values are transfered to the DECT handsets.
* see [[{{NAMESPACE}}:IP1202/IP1203_DECT_System#Configuration_of_Handset_parameters]]

See [[{{NAMESPACE}}:Concept_App_Service_Devices#Supported_DECT_handsets | Supported DECT handsets]].

=== Software rental ===
Regarding the Software Rental program and the Payment Method, please refer to:
* [[{{NAMESPACE}}:Concept_Software_Rental|Concept Software Rental]]

Software rental can be done for innovaphone Cloud installations or for software, which operates on the customer premisis. This could eventually be customer owned hardware or a privat virtual machine, managed by the customer.

==== Hardware licenses ====
Hardware licenses have to be bound on the specific device in my.innovaphone itself and currently can't be handled within the Devices App itself. So you also need to download the licenses from my.innovaphone and upload them on the device with the already known methods.

===== Hardware licenses with software rental =====
If your device has software rental licenses, you can bind hardware licenses within my.innovaphone in the software rental project itself.

===== Hardware licenses without software rental =====
If your device does not have software rental licenses, you should bind hardware licenses in a separate non rental project in my.innovaphone.

==== innovaphone Cloud ====
Inside the innovaphone Cloud, you just have to upload your activation keys with iSCs to add licenses to one or more gateways. 

==== Email expiry notifications ====
You will receive an email notification if the rental of a project expires. This notification will be sent '''seven''' weeks before the expiry and then once a week until the rental expires. 
You can configure one or more email recipients in the domain settings. 
If no email address is configured, the email address of the logged in user account is used.

==== History ====
You can download the history in the Devices App. You'll get a CSV file (semicolon separated). The date and number format depends on the selected language in the UI. 
There is also an API available for automated downloas, which is described [[ {{NAMESPACE}}:Concept_App_Service_Devices#API_to_download_rental_history|here ]].

====Own installation====
Inside your own installation, you have to register a new my.innovaphone account or you can use an existing account inside the Devices App. 
One domain inside Devices belongs to one project inside your my.innovaphone company, so you can handle multiple domains with one my.innovaphone account.

====Technical aspects====
A new rental expiration date is calculated on each license or balance change in the domain. 
So after each change new licenses with a new date are transfered to the gateways and also stored in the Devices App itself. 
If the rental expires, the gateway reboots and the licenses are not available anymore. 
The licenses are also transfered after each reconnect of a gateway to the Devices App. 
 
For license and balance changes, the Devices App must be online and have access to my.innovaphone.com!

====Usage====
You have to add (use the + symbol) a PBX and select all licenses you want to rent. 
Use the '''apply''' button to really bind these licenses. Without usage of the apply button, you can just see a precalculation of the iSCs/month and the rental end date, but nothing is really charged from your balance.

===Change of IP address/DNS name in PBX object===
If the IP address or DNS name inside the PBX object of the Devices App changes, all currently connected clients get a new Devices Registration URL and also all clients, which connect afterwards with the old host name.

== Appendix ==
=== Sample firmware.json ===
<code type="javascript">
{
"devices": [
{ "id": "IP0010", "versions": [ "13r1" ] },
{ "id": "IP0011", "versions": [ "13r1" ] },
{ "id": "IP101", "versions": [ "13r1" ] },
{ "id": "IP102", "versions": [ "13r1" ] },
{ "id": "IP1060", "versions": [ "13r1" ] },
{ "id": "IP110", "versions": [ "13r1" ] },
{ "id": "IP110A", "versions": [ "13r1" ] },
{ "id": "IP111", "versions": [ "13r1" ] },
{ "id": "IP112", "versions": [ "13r1" ] },
{ "id": "IP1130", "versions": [ "13r1" ] },
{ "id": "IP1260", "versions": [ "13r1" ] },
{ "id": "IP150", "versions": [ "13r1" ] },
{ "id": "IP2000", "versions": [ "13r1" ] },
{ "id": "IP200A", "versions": [ "13r1" ] },
{ "id": "IP22", "versions": [ "13r1" ] },
{ "id": "IP222", "versions": [ "13r1" ] },
{ "id": "IP230", "versions": [ "13r1" ] },
{ "id": "IP232", "versions": [ "13r1" ] },
{ "id": "IP24", "versions": [ "13r1" ] },
{ "id": "IP240", "versions": [ "13r1" ] },
{ "id": "IP241", "versions": [ "13r1" ] },
{ "id": "IP29", "versions": [ "13r1" ] },
{ "id": "IP3010", "versions": [ "13r1" ] },
{ "id": "IP3011", "versions": [ "13r1" ] },
{ "id": "IP302", "versions": [ "13r1" ] },
{ "id": "IP305", "versions": [ "13r1" ] },
{ "id": "IP311", "versions": [ "13r1" ] },
{ "id": "IP411", "versions": [ "13r1" ] },
{ "id": "IP6000", "versions": [ "13r1" ] },
{ "id": "IP6010", "versions": [ "13r1" ] },
{ "id": "IP800", "versions": [ "13r1" ] },
{ "id": "IP810", "versions": [ "13r1" ] },
{ "id": "IP811", "versions": [ "13r1" ] },
{ "id": "IPVA", "versions": [ "13r1" ] }
],
"versions": [
{ "id": "13r1", "build": "131705", "text": "13r1 dvl [131705]", "wiki": "" }
]
}
</code>

=== Sample apps.json ===
<code type="javascript">
{
"apps": [
{
"id": "apidemo",
"folder": "apidemo",
"binary": "apidemo",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "Apidemo",
"description": "The Apidemo"
},
{
"id": "appstore",
"folder": "appstore",
"binary": "appstore",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "AppStore",
"description": "AppStore"
}
]
}
</code>

=== Sample software.json ===
<code type="javascript">
{
"software": [
{
"id": "myappsandroid",
"folder": "myappsandroid",
"binary": "myapps.apk",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "myApps Android",
"description": "myApps for Android"
},
{
"id": "myappswindows",
"folder": "myappswindows",
"binary": "myAppsSetup.msi",
"versions": [
{ "id": "13r1", "build": "131705", "label": "dvl" }
],
"manufacturer": "innovaphone",
"title": "myApps Windows",
"description": "myApps for Windows"
}
]
}
</code>

=== Sample phoneplatform.json ===
<code type="javascript">
{
{
"phoneplatforms": [
{
"id": "arm64",
"text": "Phone Platform",
"file": "phone-platform.img",
"folder": "yocto2",
"version": "2063"
}
],
"devices": [
{
"id": "IP270",
"phoneplatforms": [
"arm64"
]
}
]
}
</code>

=== API to download rental history ===

You can download the history as a UTF-8 CSV file with simple '''HTTP GET''' requests with '''digest''' authentication. 
The CSV file uses the semicolon as delimiter. 
 
The URL to download the history is e.g.: 
'''<code>https://mydomain.com/mydomain.com/devices/csvapi?...</code>'''

You can find this path by editing the instance in the AP manager.
In the listed paths, you'll find something which ends with csvapi

In the innovaphone Cloud environment, the URL can be retrieved by taking a look at the Devices App object inside the cloud PBX and replacing the ending '''innovaphone-devices''' with '''csvapi''' inside the App URL, so it looks e.g. like this:

https://cloud-apps0.innovaphone.com/cloud.innovaphone.com/devices/csvapi

====CSV columns====
Most columns should be self explaining, but the column '''invoice reference''' refers to a value which you can configure manually in the domain settings in the Devices App!

====Digest authentication====
You can login with two different username/password combinations, while the domain is the digest username:

* If you use the domain and password of your Devices App instance inside the AP Manager, you have automatically access to all domains. 
* If you use the domain name of any domain as digest username and the configured domain password, you'll have access to this domain and all domains to which this domain has access to

====Query parameters====
The following query parameters can be used (don't forget to URL encode the parameter values, if neccessary!):
* all: if '''1''' or '''true''', the history is queried for all domains where the digest user has access to
* domain: required, if ''all'' is not set
* lang: the output language of the CSV file, which also controls date and number formats, e.g. '''en''', '''de''', ...
* tz: the timezone for dates, e.g. '''Europe/Berlin'''
* type: two types are available:
** '''history''': history which contains changes
** '''overview''': a monthly overview with the iSC costs at the first of the last months
* from: unix timestamp (UTC) in milliseconds, ignored for type=overview
* to: unix timestamp (UTC) in milliseconds, ignored for type=overview

====Example requests====
* <code>https://mydomain.com/mydomain.com/devices/csvapi?domain=mydomain.com&type=overview&lang=en&tz=Europe%2FBerlin</code>
* <code>https://mydomain.com/mydomain.com/devices/csvapi?domain=mydomain.com&type=history&lang=en&tz=Europe%2FBerlin&from=1601903431000&to=1601903385000</code>
* <code>https://mydomain.com/mydomain.com/devices/csvapi?all=1&type=overview&lang=en&tz=Europe%2FBerlin</code>

=== Supported DECT handsets ===

The following handsets are supported for update jobs and the DECT handsets configuration:

* IP64
* IP65
* D81
* D83

== Known issues ==

===SoftwarePhone===
The Devices App is not meant to be used with the windows SoftwarPhone standalone installation.

== Related Articles ==
* [[Howto:Software_Rental]]

Reference15r1:Concept myApps platform services

2025-06-30T08:42:51Z

Dde:

[[Category:Concept|myApps]]

myApps platform services provide various operating system specific services which can be used by other ''Apps'' running in the [[{{NAMESPACE}}:Concept myApps|myApps client]]. Those services typically are not available in the browser's JavaScript environment and hence must be implemented in native platform code. Therefore, the platform services are installed as native executable on the respective platform.

When myApps is started in a web browser (and hence has no access to the platform services), some Apps will use [https://en.wikipedia.org/wiki/WebRTC WebRTC] services implemented by the browser instead. For ease of reference, features available in this scenario are also described here.

On windows, the platform services also come with their own web browser in which the myApps web App will be started then. This browser is based on google's [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium] open source software.
= Applies To =

* [[{{NAMESPACE}}:Concept myApps|myApps]]
* myApps for Windows
* myApps for macOS
* myApps for iOS
* myApps for Android

* myApps Web App (WebRTC)
version 14r2

=Features=
Not all features are available or required on all platforms.
{|
! style="text-align: left; font-weight: bold" | Feature

! style="text-align: left; font-weight: bold" | Description

! style="text-align: left; font-weight: bold"| Availability
|-

| || || Windows || iOS || Android || macOS || Browser<ref>This refers to the myApps web application running in a browser with no platform services available</ref>

|-
| audio || manage local audio devices to record and playback audio conversations || ✔ || ✔ || ✔ || ✔ || ✔ (audio available but devices managed by web browser)
|-

| video || manage local displays and cameras to capture and render video live stream || ✔ || ✔ || ✔ || ✔ || ✔ (video available but devices managed by web browser)

|-

| ringer || manage local ringing device || ✔ || ✔ || ✔ || ✔ || ✔
|-

| application sharing

|-

|   presenter || share an application || ✔ || ✗ || ✔ || ✔ || ✔
|-

|   consumer || view an application shared by the peer || ✔ || ✔ || ✔ || ✔ || ✔

|-

| hot keys || capture key presses for quick invocation of phone apps (e.g. dial selected number) || ✔ || ✗ || ✗ || ✔ || ✗
|-
| tel: and sip: URI handler || intercept clicks on tel: and sip: links in web sites to invoke phone apps || ✔ || ✔ || ✔ || ✔ || ✗

|-
| user activity || set presence state according to user activity || ✔ || ✗ || ✗ || ✔ || ✔<ref>limited, see [[#User activity|User activity]] below</ref>

|-

| docking || myApps can be docked persistently to the right or left edge of your screens || ✔ || ✗ || ✗ || ✗ || ✗

|-

| multi-windowing|| Apps can be launched in separate windows|| ✔ || ✗ || ✗ || ✔ || ✗

|-

| recording|| Calls can be recorded to recording app|| ✔ || ✔ || ✔ || ✔ || ✗

|-
| notifications || ||
|-
|   display notifications || display notifications with OS standard mechanism || ✔ || ✔ || ✔ || ✔ || ✔
|-
|   push notifications || receive push notifications while myApps is not running || ✗ || ✔ || ✔ || ✔ || ✔<ref>The browser needs to be running in order to receive push notifications.</ref>
|-
|   chat and apps || display notifications for chat and other apps || ✔ || ✔ || ✔ || ✔ || ✔
|-
|   calls || display notifications for incoming calls || ✔ || ✔ || ✔ || ✔ || ✗<ref>Call notifications are only displayed locally while the phone or softphone app is started.</ref>
|-

| phone book access || access local phone book || ✔ || ✔ || ✔ || ✔ || ✗
|-
| office presence provider || maps PBX presence state to Microsoft office presence state || ✔ || ✗ || ✗ || ✗ || ✗
|-

| external application start || start arbitrary external applications for calls || ✔ || ✗ || ✗ || ✔ || ✗

|-

| app proxy|| a caching proxy that provides app persistence || ✔ || ✔ || ✔ || ✔ || ✗

|-

| auto update || automatically updates myApps platform services to the same version the PBX has || ✔ || ✔ || ✗ || ✔ || ✔<ref>The then-current web app is always loaded from the PBX upon startup and hence up-to-date by definition</ref>
|-

| three party conference || initiate 3-pty-conference using Softphone-App || ✔ || ✔ || ✔ || ✔ || ✗

|-
| exclude VPN || disable use of VPN connections for audio and appsharing || ✔ || ✔ || ✔ || ✔ || ✗

|}

<references/>

=Requirements=
* innovaphone PBX 14r2 and up

== Hardware ==
Recommended hardware requirements
* Processor: Dual-core 2Ghz or higher
* RAM: 4 Gb

== myApps for Windows ==
* Windows 10 and up
* Windows Server 2016 and later versions

=== 32 & 64 bit Windows ===
* 32 bit Windows: install the myAppsSetup32.msi from the App Store
* 64 bit Windows: install the myAppsSetup.msi from the App Store
** the 64 bit variant still installs into Program Files (x86), as the main myApps.exe is still a 32bit application
** the 64 bit variant just contains an additional 64 bit binary for the outlook search

=== Windows N editions ===

Windows N editions are missing the ''Media Feature Pack'' which is pre installed on other Windows versions.

Please install the pack from [https://www.microsoft.com/en-us/software-download/mediafeaturepack Microsoft (Windows 10 pack)] before you install myApps. The installer will check if the file <code>C:\Windows\SysWOW64\mfplat.dll</code> exist on your system.

Make sure to install the correct pack depending on your Windows version! There are different packs for Windows 10 1703, 1803, 1809 and 32bit or 64bit etc.

NB: Sometimes the myApps installation will not work even though the media pack is already installed. This is because the installer has no read access to check if the package is already installed. If the above-mentioned file exists and the installer asks to install the Windows Media Feature Pack nevertheless, you have to start the myApps install with administrative rights.

=== Terminal Server environments ===

Audio driver was removed if myApps discovers that it is running in a terminal server environment like Citrix.

The audio driver is needed for the Softphone App but the Softphone App should not use an audio driver at the server side because the audio devices are plugged locally and there would be a delay sending and receiving audio data with the server.

If a customer wants to use the Softphone App at the server side he needs to make use of the myApps Plugin for virtual desktops solution:

[[{{NAMESPACE}}:MyApps_Plugin_for_Virtual_Desktops|Reference15r1:MyApps_Plugin_for_Virtual_Desktops]]

== myApps for macOS ==
* macOS 10.13 or higher

== myApps for iOS ==
* iOS 12 or higher

== myApps for Android ==
* Android 6.0 or higher. Android 6.x may need an update of the Chrome browser.

= Licenses =
* No license needed for myApps platform services

= Overview =
myApps platform services is a native executable that is installed using the standard mechanisms on the respective operating system. It provides various advanced services which can be used by the myApps web client code as well as the Apps running in the myApps context.

Also, on Windows, the platform services come with their own, dedicated browser to run myApps in. This browser is based on [https://en.wikipedia.org/wiki/Chromium_(web_browser) Chromium]. On iOS, macOS and Android, it is based upon native embedded web view facilities (such as WKWebView) instead.
== Components ==

=== RTP service for audio and appsharing ===
The RTP service provides audio and appsharing as a video stream. VoIP RTP endpoints (e.g. for softphones). It supports STUN, TURN, ICE, SRTP, DTLS. Note however that unlike WebRTC, these endpoints do not ''require'' ICE and DTLS. In other words, they can communicate also with non-compliant (i.e. older) VoIP devices.

Note that the available capabilities when not running the myApps platform services depend on the used browser's WebRTC implementation. See your browser documentation for details.

Apps can request RTP channels using the [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol]'s ''AllocChannel'' message.

===== RTP ports=====

{|

| audio || 50000 -> 50099

|-

| video (app sharing) || 50100 -> 50199

|}

The RTP service will enumerate all local interfaces and create local HOST candidates for ICE. There is an option however to disregard VPN interfaces (more precisely such interfaces with type of ''IF_TYPE_PPP'' or ''IF_TYPE_TUNNEL''). This can eliminate quality issues when RTP data is transmitted through TCP based VPN tunnels.

SRFLX and RELAY candidates are obtained using the STUN and TURN server configuration passed by the App (e.g the ''softphone'' App) as part of the ''AllocChannel'' request.
<code>{"mt":"AllocChannel","channel":"81429cba-396d-43de-8a76-ec020ba8796e","iceServers":[{"urls":"turn:myturn.domaincom:4077?transport=udp","username":"turnuser","credential":"pwd","credentialType":"password"},{"urls":"stun:mystun.domain.com:4077"}],"dn":"Foo Bar","type":"RemoteRtp","kind":"video"}</code>

===== Codecs =====

The installed myApps launchers provide codecs that can be used by softphone apps for media streams. When running in a web browser the codecs depend on the browser version and operating system. See the documentation of your browser for details.

The following codecs are supported:

{|
!style="text-align:left;width:100px;"|Codec
!style="width:100px"|Windows-Launcher
!style="width:100px"|Android
!style="width:100px"|iOS
!style="width:100px"|macOS
!style="width:100px"|Firefox (Browser)
!style="width:100px"|Chrome (Browser)
!style="width:100px"|Edge (Browser)
!style="width:100px"|Safari (Browser)
!style="width:100px"|Opera (Browser)
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Audio
|-
|G711A
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G711u
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G722
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|G729
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729A
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729B
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|G729AB
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|-
|[https://caniuse.com/#search=Opus OPUS-NB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|[https://caniuse.com/#search=Opus OPUS-WB]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Video
|-
|[https://caniuse.com/#search=VP8 VP8]
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|-
|[https://caniuse.com/#search=VP9 VP9]
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔**
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔**
|-
|[https://caniuse.com/#search=H264 H264]
|style="color:green;text-align:center"|✔**
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|-
|style="text-align:left; background-color:lightgray" colspan="10"|Application Sharing
|-
|Share
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|-
|Watch
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔*
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:green;text-align:center"|✔
|style="color:red;text-align:center;font-weight:bold;"|X
|style="color:green;text-align:center"|✔
|}

''* small presentation only'' 
''** only for 1:1 calls, not for conferences

===== Video capture =====

The default resolution for video capture is 1920x1080 if available. Otherwise, 1280x720, 640x480, 352x288 or 320x240 will be used. The frame rate is 30 fps if available, otherwise 15 fps. The resulting average bandwidth could reach 1 Mbps.

===== Application sharing =====

Screen content will be transmitted as video stream by the presenter

===== Device handling =====

The RTP service enumerates microphones, loudspeaker, cameras and ringing devices and notifies apps when devices come and go. It is up to the apps using the devices to store preferences.

The RTP service also enables some extended features (such as hook switch or volume control) for supported USB headsets or Bluetooth headsets connected to myApps.
The supported headset-SDKs determine which headset vendors are recommended to be used with the myApps softphone app. 

For this to work, the following vendor specific development kits are integrated in our myApps client. Be aware that the SDK are updated within our Service release :

{| class="wikitable"
|-
! SDK Vendor !! Supported OS !! SDK Version !! innovaphone Service Release
|-
| Jabra|| MacOS || 1.12.2.0 || 13r3sr9
|-
||| Windows || 1.12.2.0 || 13r3sr10
|-
| Epos ''(formerly Sennheiser)'' || MacOS || 12.4.0.5478 || 14r1sr3
|-
||| Windows || n.a. - [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|to be installed separately]]|| 13r3sr10
|-
| Poly ''(formerly Plantronics)'' || MacOS || 3.25.53799.37131 || 13r3sr9
|-
||| Windows || 3.25.53800.37131 || 13r3sr10
|-
| Yealink || MacOS || 3.1.1.20 || 14r1sr3
|-
||| Windows || 3.1.1.20 || 14r1sr3
|}

Notes:
* It is possible to inhibit the start of the Sennheiser SDK (SenncomSDK.exe) using the <code>DISABLEHEADSETS</code> directive of the installer (see [[#MSI Parameters and install options| MSI parameters]] below).

* Starting with V13r3sr10, the Epos-SDK needs to be installed separately using the Epos Connect software to ensure full compatibility between current Epos headset models and native myApps-Windows client. For details [[Support:13r3 sr10 MyApps Windows Client - Epos/Sennheiser-Headsets require installed Epos-Connect Software|refer to this article]].


===== Ring tones =====

Ring tones can be played. Apps can choose the tone from a pre-defined list of ring tones.

On Windows, custom ring tones can be uploaded as .mp3 files to the <code>ringtones</code> sub-directory of myApps' roaming directory (which usually is in <code>C:\Users\...\AppData\Roaming\innovaphone\myApps\ringtones</code>).

On Android, custom ring tones can be added to the system via Android settings.

On iOS, custom ring tones can be uploaded as .mp3 files to the <code>Ringtones</code> subdirectory of the myApps file share that is available in iTunes if the iPhone has been connected via USB.

On macOS, custom ring tones can be uploaded as .mp3 files to <code>~/Library/Containers/com.innovaphone.client-macos/Data/Documents/Ringtones</code>.

===== Debugging =====
For extended debugging, turn on the ''Audio'', ''Media'' and ''AppSharing'' traces in myApps.

=== Hot keys ===
On Windows and macOS systems, myApps platform services can listen for hot keys and invoke certain functions. Invocation is done by sending API messages to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

The hot keys can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below. Any of the function keys F1 to F11 (optionally combined with up to two modifier keys ''alt'', ''ctrl'', ''shift'' or ''win'') can be chosen for each function. If you do not want to start the call with "Hotkey+Enter" because you would have to wait for the focus, the hotkey can also be pressed twice and the number is dialled directly.

; dial selected number : Initiates a call using the currently selected text as target.

: A ''PrepareCall'' message with the ''text'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":"mt":"PrepareCall","text":"13","adjust":true}}</code>

; accept call : Accepts a currently alerting call.

: A ''ConnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"ConnectCall"}}</code>

; reject/disconnect call : Rejects a currently alerting call or disconnects an active call.

: A ''DisconnectCall'' message will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].

:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"DisconnectCall"}}</code>

=== URL Handler ===

On Windows systems, two URI-handler are installed with the myApps platform services. Windows will call up this URI handler when a user clicks on an appropriate link, for example in a web site.

The handler will the send an API message to myApps which passes it to an appropriate API provider (in the cases described here, this will be a ''phone'' or ''softphone'' or ''rcc'' App typically. See [[{{NAMESPACE}}:Concept_myApps#Client_APIs_and_default_apps | Client APIs and default apps]] for more details about this mechanism.

; tel URI : call a number, e.g. <code>tel:4711</code>

: A ''PrepareCall'' message with the ''num'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","num":"4711","adjust":true}}</code>
; sip URI : call a SIP name, e.g. <code>sip:zkl@innovaphone.com</code>

: A ''PrepareCall'' message with the ''sip'' argument set to the selected text and the ''adjust'' argument set to <code>true</code> will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm ''com.innovaphone.phone'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","sip":"zkl@innovaphone.com","adjust":true}}</code>
; im URI : start chat with SIP name, e.g. <code>im:zkl@innovaphone.com</code>

: A ''StartChat'' message with the ''sip'' argument set to the selected text will be sent to the [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm ''com.innovaphone.chat'' API].
:: <code>{"mt":"ApiRequest","apiId":"com.innovaphone.chat","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartChat","sip":"zkl@innovaphone.com"}}</code>

On macOS systems myApps might be made the default application to handle tel URI e.g. <code>tel:4711</code> via Apple FaceTime. Open the "FaceTime" menu "Settings..." and select myApps as "Default for phone calls".

On iOS ''tel'' URIs are always dialed via GSM. Therefore myApps iOS also reacts to URI schemes ''com.innovaphone.tel'', ''com.innovaphone.sip'' and ''com.innovaphone.im'', e.g. <code><nowiki>com.innovaphone.tel:4711</nowiki></code>, <code><nowiki>com.innovaphone.sip:zkl@innovaphone.com</nowiki></code>, <code><nowiki>com.innovaphone.im:zkl@innovaphone.com</nowiki></code>.

=== User activity ===
On Windows and macOS systems, the myApps platform services can monitor user keyboard/mouse activity and change the user's presence state after a certain amount of inactivity. The timeout can be specified using the ''advanced settings'' user interface (see [[#UI elements| UI elements]] below.

myApps will then send a [https://sdk.innovaphone.com/doc/appwebsocket/myApps.htm#SetUserActivity''SetUserActivity''] message to the PBX using the ''myApps'' protocol.

: <code>{"mt":"SetUserActivity","inactive":true}</code>

This will change the ''status'' property of the ''im:'' contact for the user's own presence and hence result in a presence update from the PBX to myApps

: <code>{"mt":"UpdateOwnPresence","presence":[{...},{"contact":"im:","activity":"","status":"closed"}]}</code>
The ''closed'' status is reflected in the grey status color when displaying a contact [[Image:myapps-inactive.png|myapps-inactive.png/|myapps-inactive.png/]].

On iOS and Android, the state is set to ''inactive'' as soon as the App is brought to background.
When myApps platform services are not available (i.e. when running the web application in a browser solely) a limited user activity monitoring is available: the state is set to active when the web page is not used for more than 5 minutes.

=== Recording ===

The new launcher offers the possibility to record the audio of incoming and outgoing calls. In order to activate that functionality the URL of the recording instance must be configured in either the PBX (PBX->myApps->Config: Recording URL) or the softphone App (Settings->Audio Recording (URL))

[[Image:PBX-Recording-Settings.png|pbx-recording-settings.png/|pbx-recording-settings.png/]] [[Image:Recording-Softphone-Settings.png|recording-softphone-settings.png/|recording-softphone-settings.png/]].

As long as that URL is configured the audio data of all calls are stored as pcap-files under that URL.
If the URL points to a CF device in the PBX, write access must be granted for that URL (PBX->Services->HTTP->Server:Public compact flash access) and if the URL points to the recording app, the files can be accessed via the recording app [[{{NAMESPACE}}:Concept_App_Service_Recordings|recording]].

Under PBX->myApps the administrator can set a certain default behaviour of the audio recording like whether or not the recording should start automatically at the beginning of the call (Recording by Default ON/OFF), only calls with external numbers should be recorded (Record external calls only) or whether or not the user should be able to start/stop the recording himself (Allow user incall recording control). Except for the last parameter these parameters can also be modified by the user in its softphone settings if the administrator doesn't set the FORCE flag.

If the user was allowed by the admin to control the recording a recording switch is active during the call when the "Media" Panel is opened. There the audio recording may be stopped and continued at will. A red recording notice is shown in the top right corner when the recording actually takes place.

[[Image:Recording-incall-switch.png|recording-incall-switch.png/|recording-incall-switch.png/]]

=== Notifications ===

The myApps platform services can use the OS specific notification mechanism (e.g. ''desktop notifications'' on Windows) to display messages (e.g. ''incoming new chat message'') to the user.

Note that the actual rendering of the notification is under control of the OS. Therefore, myApps must be allowed to show notifications and its appearance can be restricted by OS native settings.

==== Microsoft Windows Notifications ====

Microsoft Windows Server editions (2016, 2019, 2022) are just capable of showing a single ''IncomingCall'' notification at the same time (we couldn't find a workaround for this limitation). 
An ''IncomingCall'' notification is visible the whole time instead of being moved to the action center after a certain time. 
 
A notification about a missed call uses the ''IncomingCall'' type so that this notification is visible until the user returns. 
Due to the above limitation, on a new arriving call such a missed call notification is transformed to a default notification which will be moved to the action center automatically. 
 
On non server editions, you can have multiple IncomingCall notifications at the same time (so two parallel incoming calls will be indeed notified at the same time), but the missed call notification handling is the same on both platforms!

Thus there will be always just '''one''' missed call notification visible and previous missed calls can be found inside your action center!

To see myApps notifications, ensure:
* System -> Notifications
** enable notifications
** disable "Do not disturb" or allow myApps as priority application while "Do not disturb" is active
** enable notifications for myApps in the list of applications
* System -> Focus
** if a focus session is active and the "Do not disturb" is activated during a focus session, make sure that myApps is a priority application (see above)

==== macOS Notifications ====
Notifications are the same as on Windows.
The difference is, that for macOS, notifications need to be allowed in the system settings.
Go to Notifications - myApps, select Banner and enable all check marks.

=== Local phonebook access ===
'''Contact Search:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm ''com.innovaphone.search'' API]]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Search'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{"mt":"Search","type":"contact","search":"john doe"},"apiId":"com.innovaphone.search"}</code>
Search results are delivered as ''SearchInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{"mt":"SearchInfo","relevance":2000,"adjust":true,"type":"contact","contact":{"givenname":"John","sn":"Doe","company":"ACME","position":"Head of everything","telephonenumber":["11111","22222"],"homephone":["+4944444","33333"],"mobile":["+49 (123) 55555"]}},"api":"com.innovaphone.search"}</code>

'''Reverse Lookup:''' The myApps platform services implement an ''API provider'' for the [http://sdk.innovaphone.com/web1/com.innovaphone.phonelookup/lib1_api_phonelookup.htm ''com.innovaphone.phonelookup'' API]. They perform search capabilities on the OS' local phone books which can be used by Apps like the ''phoneapp''.

Apps would send a ''Lookup'' request to the API:

: <code>{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{ mt: "Lookup", prefixIntl: "000", prefixNtl: "00", prefixExt:"0", area: "7031", country: "49", lookup: "0004970311234567" },"apiId":"com.innovaphone.lookup"}</code>

Search results are delivered as ''LookupInfo'' messages:

: <code>{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{mt: "LookupInfo", dn: "Jake Blues", contact: { telephonenumber: ["0004970311234567"], givenname: "Jake", sn: "Blues", company: "Blues Brothers" </code>

==== Windows ====
On Windows, the search and lookup are performed in all of the user's Outlook contact folders. As opposed to the search implemented in the ''Contacts'' and ''Users'' App, all items are returned which match any of the search words (i.e. searching for ''a b'' will return items matching either ''a'' or ''b'').

; searched properties : firstname, lastname
; returned properties : Following Outlook contact phone number properties are returned (if available):

:* OFFICE_TELEPHONE_NUMBER as ''telephonenumber''
:* OFFICE2_TELEPHONE_NUMBER as ''telephonenumber''
:* HOME_TELEPHONE_NUMBER as ''homephone''
:* HOME2_TELEPHONE_NUMBER as ''homephone''
:* MOBILE_TELEPHONE_NUMBER as ''mobile''
:* BUSINESS_FAX_NUMBER as ''facsimiletelephonenumber''
Note that contact information is cached in the search provider. Updated contacts may therefore become effective after a while only.
Outlook search will create its own trace file <code>myAppsOutlookSearch-</code>''date-time''<code>.txt</code> in the standard trace directory.

This search provider is always installed and can be disabled. There is no need (nor possibility) to enable it in the ''Apps'' tab of the PBX's user object. Also, no ''App'' object needs to be created for it.

==== Android/iOS ====
The search and lookup are performed in the contacts.

==== macOS ====
The search and lookup are performed in the contacts. If you wish to disable local contact lookup, go to system settings - Security & Privacy and disable the access to contacts for myapps.

=== Microsoft Office integration ===

The myApps platform services has a ''office presence provider'' that can provide the user's presence state to Office applications. See [[{{NAMESPACE}}:Concept_myApps_Office_Integration|myApps Office Integration]] for details.

This feature is installed by default. However, it can be disabled using the ''OFFICEPRESENCE'' MSI Parameter. Also, a check-mark is available in the setup dialog.

=== Call an external application for calls ===

Phone Apps (such as the phoneapp or softphone) can initiate the start of an external application when a new call appears (either incoming or outgoing). The actual spawning of the application is done by the myApps platform service. Also, the application properties (such as e.g. the executable's path) is configured in the myApps platform services (see [[#UI elements|Advanced settings]] in the ''UI elements'' section below).

A number of arguments can be passed to the application by substituting $-variables in the ''Parameter'' field:

; $n : phone number as dialed (called party number for outgoing calls) or received (calling party number for incoming calls)

; $N : called or calling party number in ''national'' format (e.g. 07031730090)

; $I : called or calling party number in ''international'' format (e.g. +497031730090)

: note that both $N and $I only work if $n includes both subscriber number and area code (e.g. 07031730090). Otherwise they are equal to $n

; $d : display name of peer (if known)

; $u : URI name of the peer (if available eg with a federation call)

; $c : conference id

: this is a globally unique ID for this call and may be used to relate the call to the ''guid'' found in the CallInfo structure in the [http://wiki.innovaphone.com/index.php?title=Reference10:SOAP_API#CallInfo SOAP-API] and [http://sdk.innovaphone.com/doc/appwebsocket/RCC.htm RCC-API ]. Also, corresponding [[Reference10:Call Detail Record CDR PBX|CDRs]] can be related using the ''event'' tag's ''conf'' attribute.
The start of an external application can be requested using the ''com.innovaphone.externalapps'' API.

Some setup examples are [[Howto:Integrate External Apps in innovaphone UC clients|shown here]].

=== Push ===

Mobile operating systems usually inhibit network operation of apps which run in the background or are closed by the user. This is done in order to reduce battery consumption. Unfortunately, this also stops such apps to maintain a registration by regularly sending ''keep alive'' messages to a server (in our case to the PBX). As a result, myApps will be disconnected from the PBX. When the PBX determines that there is an event for the application which needs a response, it needs to wake up the app using a dedicated channel provided by the operating system. This mechanism is know as ''push''. When running on iOS or Android, myApps supports ''push''.

For ''push'' to work, a [[{{NAMESPACE}}:PBX/Objects/Push|''push object'']] needs to be configured in the PBX . Also, it needs to be enabled on the mobile phone for the myApps app.
This mechanism is quite similar in v12 and v13, so you can refer to [[{{NAMESPACE}}:Concept_Push_Notifications_for_iOS_and_Android|Reference14r2:Concept_Push_Notifications_for_iOS_and_Android]] for more details.

Also, helpful hints can be found in [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]].

=== App Proxy ===

myApps runs further ''Apps'' (such as e.g. the ''phoneapp'') as a web page in an IFRAME of the browser myApps is running in. The App's page code is loaded either from the PBX or from an ''application platform'' (AP). This however would mean that the App's IFRAME would remain empty (a dead white screen) when the PBX or AP is not available. To make sure the App can start-up anyway, the myApps platform services feature the so-called ''App Proxy''. This is a caching proxy that caches all the App code so it is available even in case of network failure. When myApps runs in the context of the platform services, Apps are therefore not loaded from the App source directly, but from the local App proxy.

The cached files are stored in the PCs local file system in the <code>C:\Users\...\AppData\Local\innovaphone\myApps\appproxy</path></code>. There is no configuration required. However, if myApps seems to run with outdated or corrupt cached copies of the App, you can safely delete the entire directory.

=== Auto update ===

On Windows and on macOS, the myApps platform services can auto-update themselves to a common version. This is controlled by the [[{{NAMESPACE}}:PBX/Config/myApps#Launcher_Software_Update | ''Launcher Software Update'']] settings under ''PBX/Config/myApps'' in the PBX.

When myApps is started or the user logs in or myApps needs to re-connect to the PBX, the platform services will use the [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client API] to learn the desired version (''launcherUpdateBuild'', which is part of the API's ''model''). If this differs from the current version, the platform services will try to download the respective new version.

{
"mt": "ApiUpdate",
"apis": {
"com.innovaphone.client": {
"@client": {
"title": "innovaphone myApps",
"model": {
"launcher": true,
"launcherUpdateBuild": "134906",
"appStoreUrl": "http://store.innovaphone.com/release/download/"
}
}
}
}
}

The installation of the downloaded version is done by the ''innovaphonemyAppsUpdateService''. This service is installed and enabled during the initial installation of the myApps platform services. To disable auto-update, either leave the ''Launcher Software Update'' settings empty or set the service's start mode to ''disabled'' in the Windows ''services control panel''.

Note that on Windows the update service does not work on terminal servers. Administrators must do myApps base services updates using standard windows mechanisms.

Note that on macOS if myApps has been installed from the Apple Store it is assumed that auto update from the PBX is not desired and disabled therefore.

On Android/iOS/macOS updates can be downloaded from the respective app store.

The ''Devices'' app can not update software installed on Windows PCs directly. However, when the PBX is updated using an ''update job'' in the ''Devices'' App, the ''Launcher Software Update'' settings will be updated accordingly and hence the myApps base services will ultimately also be updated to the same version.

==== Auto update flow on Windows ====

* On start of myApps, myApps checks if an update is available and ready for installation
** if yes, the update is installed directly, without user interaction (a popup is shown during the installation)
** if not, myApps starts
* if an update is available while myApps is already running, an update notification will be shown which let's the user choose to install the update now or later (the notification will then popup again after one hour)

==UI elements ==
There are a few user interfaces provided by the platform services:
===tray-icon (Windows only) ===
::[[Image:myapps-tray.png|myapps-tray.png/|myapps-tray.png/]]
:Allows to
:* terminate myApps
:* toggle the ''autostart'' state
:* toggle the ''show in task bar'' state
:* open the trace folder
:
=== PBX connect form===
:: [[Image:myapps-connect.png|myapps-connect.png/|myapps-connect.png/]]
: Allows the user to specify the connect data for the PBX (i.e. IP address or DNS name)
:
=== Advanced settings===
::[[Image:myapps-settings0.png|myapps-settings0.png/|myapps-settings0.png/]]
::[[Image:myapps-settings.png|myapps-settings.png/|myapps-settings.png/]] [[Image:myapps-settings2.png|myapps-settings2.png/|myapps-settings2.png/]] [[Image:myapps-settings3.png|myapps-settings3.png/|myapps-settings3.png/]]

: Allows to modify various platform dependant settings (such as e.g. the hotkey selection on Windows)

== Interfaces ==
=== Provided APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.search/lib1_api_search.htm com.innovaphone.search] : access to local phone book entries by the [[#Local phonebook access|Local phonebook access]] component.
; [http://sdk.innovaphone.com/web1/com.innovaphone.launcher/com.innovaphone.launcher.htm com.innovaphone.launcher] : display of OS specific user notifications and receipt of related user actions
; com.innovaphone.notificationhandler : reports back click on a notification.
; com.innovaphone.externalapps : to start external applications, see [[#Call an external application for calls|Call an external application for calls]] above

=== Used APIs ===

; [http://sdk.innovaphone.com/web1/com.innovaphone.phone/com.innovaphone.phone.htm com.innovaphone.phone] : used to initiate new or manipulate existing calls by the [[#Hot keys|Hot keys]] and [[#URL handler|URL handler]] components.

; [http://sdk.innovaphone.com/web1/com.innovaphone.chat/com.innovaphone.chat.htm com.innovaphone.chat] : used to start a new chat by the [[#URL handler|URL handler]] component.

; [http://sdk.innovaphone.com/web1/com.innovaphone.client/lib1_api_client.htm com.innovaphone.client] : the model is used to learn the update settings, see [[#Auto update|Auto update]] above

=== Protocols ===

; [https://sdk.innovaphone.com/doc/launcher/Media.htm Media Protocol] : used by apps to allocate RTP channels, see [[#RTP service for audio.2C video and data|RTP service for audio, video and data]] above

== Related App Services ==

none

== Known limitations ==
; Incoming call as banner on myApps for iOS : Since iOS 14 the iOS CallKit presents incoming calls as a banner leaving the original green answer button of myApps visible. Use only the blue button of the banner to accept the call or change iPhone Settings, App "Phone", "Incoming Calls" to "Full Screen" to hide the myApps user interface again during call answering.

; Call answer in speakerphone mode even with active Bluetooth headset on myApps for iOS : This causes unwanted speakerphone operation if the smartphone is used with a Bluetooth car audio system. The behaviour can be changed by selecting ''Bluetooth Headset'' in this setting:
:''iOS Settings->Accessibility->Touch->Call Audio Routing: Automatic / Bluetooth Headset / Speaker''
:''iOS Einstellungen->Bedienungshilfen->Tippen->Anrufaudioausgabe: Automatisch / Bluetooth-Headset / Lautsprecher''

; Windows Server 2016 (Windows 10 Build 1607) : windows just shows the first notification. Further notifications aren't displayed until the previous ones are removed from the notification center. Current windows builds do not show this behaviour anymore.

; Problems on Mac computers with Yealink USB headsets
: we have received reports that myApps quits unexpectedly on some Mac computers when a Yealink headset is plugged in. Unfortunately, we could not find out the cause yet. If you use Yealink USB headsets and have a similar issue, please open a support ticket and send myApps traces.

; Poly / Plantronics headset buttons only functional if myApps is started with Rosetta
: myApps macOS supports Apple M1/M2 hardware natively. However, the Poly / Plantronics headset SDK is only available for Intel platform and thus myApps needs to be started via Apple's Intel emulator Rosetta if a Poly / Plantronics headset is used. This is done with right-click on the myApps executable, ''Information'', ''Open with Rosetta''.

; Windows surface devices may not work correctly
: Chromium does not get touch keyboard events. USB Keyboards may not be recognized either.

= Installation =

== Windows ==

myApps platform services are installed on Windows using the .msi file found in the ''myApps Windows'' package from [https://store.innovaphone.com/release/download.htm store.innovaphone.com].

myApps can update itself automatically, see [[#Auto update|Auto update]] above.

=== MSI Parameters and install options ===

The MSI installer of myApps for Windows supports the following parameters and can be edited with [https://docs.microsoft.com/en-us/windows/win32/msi/orca-exe Microsoft Orca]. You can add your parameters in the table ''property''.

; SERVER (REG_SZ): the PBX's server URL
; OFFICEPRESENCE (REG_DWORD): '''false''' to disable presence integration in Microsoft Office
: this is also available as a check-mark when running the install manually

; DISABLEHEADSETS (REG_DWORD): '''true''' to disable headsets support, see [[#Device handling|Device handling]] above

; EXTERNALAPPS (REG_SZ): pre-define external applications, see [[#Call an external application for calls|Call an external application for calls]] above
: e.g. <code>"{""externalApps"":[{""id"":0,""name"":""Wireshark"",""path"":""C:\\Program Files\\Wireshark\\Wireshark.exe"",""param"":""test $I""}]}"</code>

; FORCERESTART (REG_DWORD): '''true''' (or any string ...) kills myApps during the installation and restarts it for the currently logged in user, if it was running

; DISABLELOCALHOST (REG_DWORD): '''true''' to disable use of '''localhost''' string to access the local webserver. Use '''127.0.0.1''' instead

; EXCLUDEINTERFACES (REG_SZ): some VPN interfaces are not detected by Windows as IF_TYPE_PPP or IF_TYPE_TUNNEL and therefore the '''media outside VPN''' setting is not taking effect. With this option interfaces can be pre-defined that will not be used for media. Interfaces must be comma separated
: e.g. <code>EXCLUDEINTERFACES="172,192.168,10.10"</code>

Current settings are stored in the registry at <code>Computer\HKEY_CURRENT_USER\Software\innovaphone\myApps</code> or at <code>Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\innovaphone\myApps</code>

Boolean values like OfficePresence are stored in registry entries with type REG_DWORD and values 1 or 0. 0 disables the setting and 1 enables it.

== iOS ==

myApps platform services are installed on iOS by loading ''innovaphone myApps'' from the ''App Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist>

== macOS ==

myApps platform services might be installed directly from the Apple store. An installer package <code>myapps.pkg</code> and a disk image <code>myapps.dmg</code> is also available from the innovaphone app store. Install <code>myapps.pkg</code> by double-click on the file and follow the instructions of the installer. myApps becomes available in the Applications folder and can be opened by double-click. Or download and open <code>myapps.dmg</code> and double klick myApps. If desired integrate it into the app dock by right click, ''Options, Keep in the dock''.

If installed from the innovaphone app store, myApps can update itself automatically, see [[#Auto update|Auto update]] above.

If installed from the Apple store, macOS notifies about updates on the Apple store. myApps [[#Auto update|Auto update]] is disabled then.

If a clean-install of the client is necessary, the folder "/Users/username/Library/Containers/myapps" needs to be deleted. To be on the safe side also delete it from the trash bin.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying this dictionary in the MDM
<plist>
<dict>
<key>server</key>
<string>pbx.example.com</string>
</dict>
</plist>

=== Preferences ===

macOS supports preference settings that can be set via a shell command or via Mac remote management

defaults write com.innovaphone.client-ios-14r1 server "PBX-server-URL"

The following parameters and can be set through this method:

; server: the PBX's server URL

=== Setting myApps as Default App for SIP-URLs ===

{| class="wikitable"
|defaults write com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers -array-add '{
LSHandlerURLScheme = sip;
LSHandlerRoleAll = "<CFBundleIdentifier>";
}'
|}

To find the “CFBundleIdentifier”, proceed as follows:
* In the Finder under “Applications”, search for the desired myApps client that you want to set as the default app.
* Right-click on “Show package contents” -> you will find the “CFBundleIdentifier” in the Info.plist file.

A restart of the MAC is required.

=== Using Sennheiser headsets ===
If you use Sennheiser headsets, you should also install the then-current <code>DSEA_SDK_v</code>''version''<code>.pkg</code> package, after you installed the myApps client. Without that, audio will still work, but not the controls on the headset. You will need to keep that up-to-date yourself, as it is not updated by myApps's auto-update function.

== Android ==

myApps platform services are installed on Android by loading ''innovaphone myApps'' from the ''Play Store''.

=== Configuration via MDM ===

the PBX's server URL can be pre-configured by specifying a property "server" with string value "pbx.example.com" in the MDM.

= Configuration =

== Server configuration ==
When opening myApps for the first time, the user is prompted for the Server. Usually only the hostname (DNS host name or IP address) needs to be configured.

But there are more options for special PBX configurations.

; Non-standard HTTPS port
: If the PBX uses a non-standard HTTPS port, it must be appended to the host name separated by a colon (<code>:</code>).
: Example: <code>pbx.example.com:4444</code> (expands to <code>https://pbx.example.com:4444/PBX0/APPCLIENT/appclient.htm</code>)
; DynPBX module name
: If the PBX is a DynPBX, the module id must be appended to PBX0 separated - (<code>/</code>).
: Example: <code>pbx.example.com/PBX0-1</code> (expands to <code>https://pbx.example.com/PBX0-1/APPCLIENT/appclient.htm</code>)
; Softphone physical location
: If user defined physical location shall be used for softphone, you can append it using a parameter <code>#phys=</code>.
: Example: <code>pbx.example.com#phys=slave</code> (expands to <code>https://pbx.example.com/PBX0/APPCLIENT/appclient.htm#phys=slave</code>)

Example 1: PBX pbx.example.com with standard configuration
pbx.example.com

Example 2: PBX slave.example with DynPBX module ID 1, HTTPS port 4444 and physical location master
slave.example.com:4444/PBX0-1#phys=master

=== HTTP proxy support ===

myApps platform services do support operation via HTTP proxy now. If one or more proxies have been configured in the network settings of the operating system for the active network connection, HTTP CONNECT tunnels are established.

On Windows user name and password can be specified for the tunnel servers as generic credentials in the credentials manager (Anmeldeinformationsverwaltung). The name of the credentials must be the tunnel server hostname.

On Android user name and password can be specified through Android ''Settings, Accounts'' by adding a myApps ''HTTP Proxy Credentials'' account. The name of the account must be the tunnel server hostname.

== Platform specific settings ==
When myApps runs under the myApps platform services, it will show various platform specific settings as part of its ''burger menu'', so the user can set them. See ''Advanced settings'' in [[#UI elements|UI elements]] above.

Some options can also be set globally for all myApps clients in the PBX's [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps ''Client Settings'']]
{|
! style="text-align: left; font-weight: bold" | Option

! style="text-align: left; font-weight: bold" | Description

! style="text-align: left; font-weight: bold" | Where to set

!
! style="text-align: left; font-weight: bold"| Availability
|-

| || || User menu || PBX ''Client Settings'' || Windows || iOS || Android || macOS

|-
| Autostart || Launch myApps on login || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| Appear offline after || controls after which idle time a user is considered ''inactive''. See [[#User activity|User activity]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔
|-

| Hotkeys || Hotkeys for call dial, accept, reject. See [[#Hot keys|Hot keys]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| Docking || Docking mode (left, right, none). See [[#???|??]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✗

|-

| Desktop notifications|| Turn on/off platform notifications. See [[#Notifications| Notifications]] above || ✔ ||✔ ||✔ || ✗ || ✗ || ✔

|-

| VPN || Disable VPN address for ICE candidate selection. See [[#RTP ports| RTP ports]] above || ✔ ||✔ ||✔ || ✗ || ✔ || ✔

|-

| Show in taskbar|| Show myApps in the taskbar in addition to it's tray icon. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗

|-

| Log flags || turn on/off certain trace levels. See [[#Troubleshooting|Troubleshooting]] below. || ✔ ||✔ ||✔ || ✔ || ✔ || ✔

|-

| External applications || define the applications available for Apps to be started. See [[#Call an external application for calls|Call an external application for calls]] above. || ✔ ||✗ ||✔ || ✗ || ✗ || ✔

|-

| Ring in headset || send ring tone for incoming to headset instead of loudspeaker. || ✔ ||✗ ||✔ || ✗ || ✗ || ✗
|}
== Start parameters for Windows ==

On Windows, it is not possible to pass start parameters from the [https://www.chromium.org/developers Chromium documentation] to the myApps process.

== OS Settings for Windows ==
Windows settings can influence the display of ''Desktop notifications''. See [https://support.microsoft.com/en-us/help/4028678/windows-10-change-notification-settings Change notification settings in Windows 10/11] for details.

=== Windows 11 ===

* Windows 11 has a feature "do not disturb". This hides notifications if enabled.
* Windows 11 has a feature "focus". This enables "do not disturb" and thus hides notifications too.
* Windows 11 has priority settings for notifications. Ensure that VoIP notifications for calls are allowed any maybe also include myApps as an App which is allowed to show notifications.

== OS settings for Android ==
; Events : The appearance of notifications can be controlled here.

; Call accounts : For proper incoming call signaling, the call account ''myApps'' needs to be enabled. Note that on Samsung smartphones the call account switch likely toggles back and a few tries may need to be done until it persists. Please double-check the state.

; Preferred Calling Account : Choose which calling account (myApps/SIM/..) should be used for outgoing calls initiated from within the native phone app / phone book.

; Background data, unlimited data usage : Grant background data use to enable ''myApps'' to connect to the PBX immediately on an incoming call.

; Overlaying : This setting is not needed if call account ''myApps'' has been enabled. Should there be a reason for not enabling call account ''myApps'', the permission for overlaying needs to be granted on Android 10 or higher for proper call signaling.

Note: If no SIM card is installed some Android smartphones exhibit a problem dialing from the smartphone contacts. The contacts app shows a choice ''Select SIM card for this call'' but all possible dialers are greyed out. In this case make myApps the default phone app in Android settings ''Apps, Default apps, Telephony''.

== OS settings for iOS ==
; Notifications : The appearance of notifications can be controlled in iOS ''Settings, myApps''.

== OS settings for macOS ==

; Notifications : The appearance of notifications can be controlled in macOS ''Preferences, Notifications, myApps''.

=Troubleshooting=

myApps platform services can write various traces for debugging. Trace can be turned on and off selectively in the [[#Advanced settings|Advanced settings]].

The following trace flags can be set:

(''Recommended trace options are: '''App, Browser, ICE, TURN, Signaling and Audio'''. Please do not activate other flags unless innovaphone support says otherwise'')

{|
!style="text-align: left; font-weight: bold" | Abbreviation

!style="text-align: left; font-weight: bold" |code

!style="text-align: left; font-weight: bold" | description

|-
| App||0x000000001|| logs from the App Service itself
|-
| DNS||0x000000008|| logs DNS requests and results
|-
| HTTP client||0x000000080|| http client logs
|-
| TLS||0x000000400|| TLS logs
|-
| TCP||0x000000800|| TCP logs
|-
| LDS||0x000001000|| local domain sockets
|-
| WebSocket client||0x000004000|| logs outgoing websocket connections
|-
| App WebSocket||0x000008000|| logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
|-
| UDP||0x000200000|| UDP logs
|-
| DTLS||0x000400000|| logs DTLS handshake and messages
|-
| Media||0x000800000|| logs media events
|-
| Media channel||0x001000000|| logs RTP/SCTP media connections
|-
| ICE||0x002000000|| logs ICE messages between peers
|-
| TURN||0x004000000|| logs TURN messages between peers
|-
| AppSharing||0x008000000|| logs AppSharing connection
|-
| Audio||0x010000000|| logs Audio connection and headset events
|-
| Video||0x020000000|| logs video connection and webcam events
|-
| Browser||0x040000000|| logs Chromium events
|-
| AppProxy||0x080000000|| logs requests which are proxied between the local webserver and the remote server
|-
| Webserver ||0x200000000|| enables webserver specific logs
|-
| Browser Console ||0x400000000|| logs browser console events
|-
| Signaling||0x800000000|| enables logs in the signaling module for debugging calls
|}
''code'' can be or'ed and used as value for the ''Log flags'' field in [[{{NAMESPACE}}:PBX/Config/myApps#Client_Settings|PBX/Config/myApps/Client Settings]].

; Windows :On Windows, traces are written to the <code>C:\Users\[UserName]\AppData\Local\innovaphone\myApps</code> directory. If you start myApps with --log-size as parameter, you can define the maximum size of a log file (e.g. --log-size=100000000 would be 100MB for each file)

:* myApps-''date-time''.txt : main log file for the platform services

:* myAppsOutlookSearch-''date-time''.txt : log file for the Outlook phone book access

:* myAppsHookController-''date-time''.txt : log file for the hot-key interceptor (see [[#Hot keys|Hot keys]])

; :myApps update installation traces are written to the <code>%windir%\temp\</code> directory.
:* myAppsInstall.txt: MSI installation file

; :myApps update service traces are written to the <code>%ProgramData%\innovaphone\myAppsUpdateService</code> directory.
:* myAppsUpdateService-''date-time''.txt: myApps update service traces

;Android : traces can be sent by e-mail.

: also, an Android device might also be connected to a PC via an USB cable to get the traces. The files can be found in <code>Android/data/com.innovaphone.clientandroid/files</code>

; iOS : traces can be sent by e-mail.

; macOS : traces can be sent by e-mail.

: also, the files can be found in <code>~/Library/Containers/com.innovaphone.client-ios/Data/Documents/</code>. Press ''Alt+N'' followed by space to get tilde ''~''.

= Known Problems =
[[:Category:Problem myApps platform services|Known Problems]]

= Related Articles =
* [[{{NAMESPACE}}:Concept_myApps]]
* [[{{NAMESPACE}}:Concept_myApps_Redundancy|Reference14r2:Concept_myApps_Redundancy]]
* [[{{NAMESPACE}}:Concept_myApps_Office_Integration|Reference14r2:Concept_myApps_Office_Integration]]
* [[{{NAMESPACE}}:Concept_myAPPs_Search_in_local-Outlook_Contacts|Reference14r2:Concept_myAPPs_Search_in_local-Outlook_Contacts]]
* [[{{NAMESPACE}}:Call_Detail_Record_CDR_PBX|Reference14r2:Call_Detail_Record_CDR_PBX]]
* [[{{NAMESPACE}}:Concept Push Notifications for myPBX iOS and Android|Reference14r2:Concept Push Notifications for myPBX iOS and Android]]
* [[Howto:Troubleshoot v13 Push with myApps for Android and iOS]]
* [[{{NAMESPACE}}:PBX/Config/myApps]]

[[Category:Concept myApps platform services]]

Reference14r2:Concept App Platform

2025-06-25T07:54:30Z

Dde: /* App Platform - x86-64 (Virtual Machine 64bit) */

= General =
* V13 uses [https://buildroot.org/ buildroot]
* this is an own (innovaphone) collection of packages
* For further information see: [https://buildroot.org/docs.html Buildroot Documentations]

== Requirements ==

* V13 or above
* Gateway (arm): IPx10 (with CF card) or IPx11 (with mSATA SSD)
* Gateway (arm64): IPx13 (with m2 SSD)
* Virtual (x86_64)
** HyperV with [https://docs.microsoft.com/de-de/windows-server/virtualization/hyper-v/deploy/upgrade-virtual-machine-version-in-hyper-v-on-windows-or-windows-server#supported-virtual-machine-configuration-versions VM-configuration Version] 6.2 (minimum: Windows 10 or Windows Server 2016)
** VMWare
** Proxmox/KVM/Qemu

== Default credentials ==

'''During INSTALL, the default passwords are replaced with the global Admin PW!'''
* SSH-Login with '''admin''' and '''ipapps'''
* root login with '''root''' and '''iplinux''' (the root login is not directly possible, you have to login as admin first and use the command ''su root'')
* manager App (web login) '''pwd'''

= App Platform - arm/arm64 (Gateway)=

* The installation image has a size of ~50MB. During installation, the following partitions are created<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 fat32: 200MB (contains ramdisk, rootfs and kernel)
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB

When comparing potential performance of the IPxx11 platform compared to the IPxx10 platform, there are some major differences:
* SSDs found in the xx11 are faster and more reliable than the CF found in the xx10
* the available RAM for the App Platform (as specified in column ''RAM for LAP (GB) out of RAM'' in chapter ''Technical data and recommended number of users supported'' of [[Howto:How to implement large PBXs#Technical data and recommended number of users supported|How to implement large PBXs]]) is factor 6 larger on the xx11 (1,536 GB) than on the xx10 (0,256 GB))
* the xx11 has gigabit Ethernet while the xx10 has 100Mbps Ethernet. The xx10 is therefore not well suited for Apps with larger network traffic, such as Recordings
* the CPU of the xx11 (although it runs on the same frequency) is roughly 20% faster than the xx10

While it is hard to predict the performance of the App Platform in a specific scenario, we see that in a real life environment an App Platform running on an xx11 platform can well support 150 users. The xx10 platform is estimated to support 120 users. Because CPU performance is the limiting factor, larger setups can be built based on the virtual machine platform (see [[#App services and multi-threading|App services and multi-threading]] below).

<references/>

= App Platform - x86-64 (Virtual Machine 64bit) =

* The default disk size is 16GB. It should be increased '''before''' the first start if needed!
* Multiple CPUs are supported, default is one CPU
* default RAM: 512MB
* static IP address, DNS, Gateway can be configured with the command '''setip''' on the console. Run '''setip --help''' to get a list of parameters. (Example: setip --addr=x.x.x.x --mask=x.x.x.x --gateway=x.x.x.x --dns1=x.x.x.x)
* If you have permission problems change to su user (Password is iplinux or your new admin password)
* To figure out your ip address you can use the command: ''ip address'' on the console.
* '''loadkeys de''' can be used to change to german keyboard layout (etc.)
* partitions<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 ext2: 350MB (contains ramdisk, rootfs and kernel)
*** the real partition format size is smaller but there is no need to monitor sda1 as sda1 won't grow during usage of the App Platform
*** sda1 is completely exchanged during an image update and its size might have changed but will never exceed these 350MB
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB
* VMWare Tools: Open VM Tools
* Qemu Guest Agent: installed since 110032
** The qemu guest agent can be configured in Proxmox with ''Virtio'' or ''ISA''. Before version 130012, you must use ISA, as Virtio was not supported with older versions.

<references/>

= Installation =
==ARM Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-armel.img'' image file.
* The installation runs without any further required step.

==ARM64 Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-arm64.img'' image file.
* The installation runs without any further required step.

==Virtual machine==

* Import the image into your server environment.
** Proxmox: follow this description here, just with the app-platform-ova.zip: https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Proxmox_VE
* Edit the disk size, if needed.
* Start the machine and wait until it reboots and starts again.
* Note: If you need to access an IP addresses available through a VPN connection from from inside the virtual machine, it could be that you need to set the network of your VM to NAT (and also add the URL for an IP to /etc/hosts)

[https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Configuration More Configuration Hints regarding VM Ware]

== Backup of the Apps ==

Each App Service can have multiple instances and each instance has its own database. The manager app itself also has its own database. 
There are no other files which need to be backuped. 
The standard way to backup the databases is through the Devices App [[{{NAMESPACE}}:Concept_App_Service_Devices#Backups]]. 
 
An alternate way is to use a command file which is similar to the command files from the firmware.

===Commands===
* '''times''' 0,12 # backup only at 0 or 12 o'clock
* '''backup-instances''' http://user:pw@ip/path/#I-#D.dump PUT
** PUT and POST are supported, all instances including the manager itself are saved
* '''backup-instance''' http://user:pw@ip/path/#I-#D.dump apidemo example.com PUT
** backup a single instance with instance name and instance domain
* '''backup-manager''' http://user:pw@ip/path/#I-#D.dump

===Hash parameters===
* #L App Platform label (neu), e.g. 10024
* #A App label (neu), e.g. 130004
* #I instance name (neu), e.g. reporting1
* #D instance domain (neu), e.g. innovaphone.com
* #m MAC address of the LAP, e.g. 00ab11eeff
* #d Current date and time (plain UTC without daylight saving and timezone adjustments) 20051010-170130
* #bn rolling backup index (n >=0 and <= 9, just one digit)
* ## escapes a hash mark

= App Platform Infrastructure and Concept =
== Webserver ==
The app platform includes a webserver that is highly optimized for handling many Websocket connections at a low memory footprint.
All apps use that webserver by registering for specific HTTP subpath. So they can all use the same HTTP/HTTPS ports - typically the standard ports.

=== Import Custom SSL Certificate ===
You have to upload a PEM Certificate with the following chain structure and without password encoding.

-----BEGIN CERTIFICATE-----
(certificate: eg. your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: eg. DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: eg. TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: eg. your_domain_name.key)
-----END RSA PRIVATE KEY-----

If you have problems generating the complete and correct certificate chain, you can use tools such as https://whatsmychaincert.com/ as an aid.
'''Please keep in mind that you never give away the private part of your key.'''

=== Known issues ===
*The app platform webserver can use only the default http/https ports 80/443.
*By design, there is no possibility to restore the default webserver certificate on the App Platform, if another certificate was once uploaded. 
**If nevertheless needed, you must login with Putty (see [[#How to retrieve files from the AP| Retrieve files]]) and execute these commands as root:
**''psql -d manager -c "DELETE FROM config WHERE name='webserverCertificate'"''
**''/etc/init.d/S92manager restart''
*The app platform webserver interprets URLs case-sensitive. In other words, <nowiki>http://<addr>/file.txt</nowiki> is not the same as <nowiki>http://<addr>/FILE.TXT</nowiki>

== Database ==
The app platform creates a database for each app instance with a given password. In the installer there will be used randomly generated passwords. You can set a new database password for every instance in the Application Platform.

The apps should store all data in that database. That makes sure that a consistent backup and restore of app instances can be done by the app platform manager.
In hosted scenarios, having separate databases for each instance also makes sure that the data of different customers are clearly separated and can easily be moved from one physical platform to another.

The default configuration decline database request from extern. If you need external access you can change the PGSQL configuration (as root) in the file ''/mnt/sda2/pgsql/pg_hba.conf''.
After editing pg_hba.conf, the database-service has to be restarted with the command <code>/etc/init.d/S50postgresql restart</code>
(Please think about it before you do it, because a better way is to create your own local app with local database access.)

You can find the official documentation for the pg_hba.conf here: https://www.postgresql.org/docs/14/auth-pg-hba-conf.html

Please note that you do this on your own responsibility, that it makes sense to create a backup of the original pg_hba.conf
and that you may break your database server if you do not know exactly what you do!

Sometimes the Apps are not proper working after this. You can wait a while until everything is working again or you go the hard way:
* stop the manager
** <code>/etc/init.d/S92manager stop</code>
* restart the database-service (maybe not really necessary, but makes a good feeling)
**<code>/etc/init.d/S50postgresql restart</code>
* start the manager
** <code>/etc/init.d/S92manager start</code>

=== Nightly database analyse ===

Every database is analysed at night to keep indexes in sync with the data. This triggers a ''vacuumdb -a -z'', which updates optimizer statistics, but does '''not''' shrink the physical size of the database. 
This must be done manually in the instance settings.

== App Platform Manager ==
The App Platform Manager is the central component of the App Platform. It does the following:
* Installing app services by downloading the binaries from an app store.
* Running and monitoring app services. If an app service crashes it is restarted, automatically.
* Management of app instances and providing them with the environment they need:
** A database
** A webserver path
** A password for authentication
* Backup and restore of app instances.
* Collecting debug information like tracing and crash dumps.
* System monitoring (CPU usage, memory usage, etc).

== App Services ==
App services are runned by the App Platform Manager. They implement an interface that is used by the manager to start, stop and configure app instances. Each service runs in a separate child process of the manager.

== App Instances ==
The actual functionality of an app service is provided by app instances. They run in the same process as the app service but have a distinct webserver path and their own database. There can be 0..n instances of an app service. Instances can optionally host (web) apps that can be opened in the myApps client.

Each instance of an App service has two passwords. The instance password itself and a database password. If you want to change it you must update the password on both sides. 
The instance password must match to the password in the corresponding PBX App objects, while one instance can have different App objects. 
The database password must be just known to the manager and not outside of the App Platform.

The ''Database name'' and ''Database user'' are both limited to a length of 63 characters. By default, the App Manager would create ''<domain>''_''<instance-name>'' as value for both. This is why it is recommended to use instance names so that length(name) + length(domain) is less than 63 characters. However, if this is not possible, you can manually shorten the suggested values (both must still be unique on your App Platform).

=== Cleanup database ===
You can cleanup the instance database inside the instance settings. This starts the vacuumdb process for the instance database which frees disk space of deleted rows.
Note that this process locks the database and that sufficient disk space is needed to complete it!

=== External database host ===
You can optionally configure an external database host, if the database shall be hosted on an external host. 
Note that the App Platform Manager still creates a local database, which is then not used as long as the external host is configured.

What are external databases useful for?:
* User data is too large (files are stored as BLOB in the database)
* Other (non-innovaphone) database servers are to be used due to other regulations
* There is already an external database cluster with its own backup/restore processes which should be used
* More performance is required (please note that a local UNIX socket provides much faster results than a remote database server). Depending on the app and the task of the app, it can still be useful to use a separate server if it is faster.

==== Supported database types ====
In principle, ''PostgreSQL'' and ''MySQL'' are supported. However, please note that the respective app must be designed for the target database server type. If an app has been developed for PostgreSQL, it cannot be operated on a MySQL server.

'''Please note:''' All innovaphone apps are developed exclusively as PostgreSQL apps.

MySQL therefore only makes sense if own apps are developed and MySQL or certain MySQL features are to be used. For such apps, it is very important to deactivate the automatic Application Platform APP-Backup.
The database backup process of the App Platform uses PostgreSQL backup commands, which is why the backup would fail, so the app must be excluded from the backup, and you must take care of the backup yourself.

==== Database creation ====
If you use an external database, you have to create the database itself.
The App Platform Manager itself creates a PostgreSQL database like this (you may respect this on your database host to be compatible with the database implementation inside the Apps):
* CREATE DATABASE "dbname" ENCODING 'UTF8';
* CREATE USER "dbuser";
* ALTER USER "dbuser" WITH PASSWORD 'dbpassword';
* GRANT ALL PRIVILEGES ON DATABASE "dbname" TO "dbuser";
* ALTER DATABASE "dbname" OWNER TO "dbuser";
* REVOKE CONNECT ON DATABASE "dbname" FROM public;

==== Database connection ====
There are different possibilities to specify the host. You can use a DNS-Name, IPv4 or IPv6. A port can be optionally added with a colon.

Our PostgreSQL implementation sets sslmode=prefer, so SSL is used by default if enabled on the server.

==== Backup/Restore ====
External databases are still backuped as normal, but you can't restore such a database with the App Platform Manager on the external host! You must restore such a dump manually on your database host.

==== Database redundancy ====
In principle, it is possible to create redundancies for failure scenarios through this function.

However, there are different scenarios that need to be evaluated on a case-by-case basis:

* One database, multiple App Platforms (primary online / secondary '''offline''') where multiple apps access the same database.
** This mode of operation is legal as long as you can really ensure that only one App Platform is active at a time.

* One database, multiple App Platforms (primary online / secondary '''online''') with multiple apps accessing the same database.
** This operating mode cannot be used for innovaphone apps, as the app itself would have to be developed for such a mode, which it is not.

However, we advise great caution here! The use of the same databases from different nodes may only be used if you can ensure that the databases or runtime environments of apps cannot get into a ''split-brain'' mode.

== Relationship between app instances and app objects in the PBX ==
Typically an app instance is connected to one or more app objects in a customer PBX. This is done by configuring the same parameters on both sides:
* URL
* Password
The password is used by the PBX for authenticating itself, users and services against the app instance.

Some apps need a websocket connection with the PBX. When "websocket" is activated at the app object, the PBX establishes a websocket connection to the app instance and provides the APIs that are configured at the app object.

=== Supported scenarios ===
It is important to understand that the concept does not do any assumptions on how PBXes and APs are correlated. So you can have
* One App Platform for one customer
* One App Platform for many customers
* Many App Platforms for one customer
* Many App Platforms for many customers

Attention: The V13 installer can only configure the scenario "''One App Platform for one customer''". If you want to have a different scenario, you have to configure it manually.

For hosting or cloud scenarios you need special scenarios. Please refer our [[Howto:V13 Hosting| V13 Hosting]] instructions.

=== Restrictions ===
Currently we don't have redundancy for app instances or App Platforms.

== Update of the App Platform itself ==
The App Platform is build on top of buildroot and will receive updates and fixes from time to time. 
You can update the used build inside the Manager App by using the '''Update''' button at the top. 

It is strongly advised to make a full backup (VM) or at least backup all apps (Gateway) before you run such an update!

After the update has been downloaded and verified, your App Platform will reboot.
You can check the installation process after the reboot with the following URL: https://IP-of-AP/manager/ramdisk.log

== App services and multi-threading ==
Each App Service runs in a single process with no multi-threading, independent of the instances of the App Service. However, each instance maintains its own database connection and the database responds to this connect with the creation of a new process. Each app service therefore uses 1+''n'' threads (where ''n'' is the number of instances). All communication between app service instances and their clients must pass the single-threaded web server. On platforms with multi-threading support (i.e. VMware or Hyper-V), up to 1 + ''m'' + ''m'' * ''n'' (with ''m'' being the number of Apps and ''n'' the number of instances per App) threads can be utilized.

= AP Manager settings =

== General ==
* ''Enable Developer mode'': in developer mode, apps can be manually uploaded without an App Store
* ''Disable App security'': each App has an own unix user and if this flag is set, the user can login with SSH for debugging
* ''App Store URL'': the URL to the App Store where Apps are searched and also an update of the AP image itself
* ''Devices app URL'': the URL to the Devices App to manage the AP through Devices
* ''Devices app URL 2'': don't use!
* ''App Platform DNS name'': currently not used
* ''NTP server 1/2'': NTP servers for this AP (in addition to NTP servers retrieved by DHCP)
* ''Timezone string'': A timezone string which is used by the App Platform Manager to do certain jobs according to the configured timezone.
** Note that this doesn't change the timezone of the linux itself!
* ''DNS server 1/2'': DNS servers for this AP (in addition to DNS servers retrieved by DHCP)
* ''Database optimization time'': The database optimization process will be started at this hour (local time), with a random offset of up to 7 hours
* ''Command file'': obsolete, use the Devices App for backups!

== Security ==
* ''Current Webserver certificates'': shows the current certificates with the ability to download them.
* ''Webserver certificate'': upload a webserver certificate in PEM format
* ''AP Manager password'': the password to the web interface of the AP Manager (normally set through Devices)
* ''Linux root user'': password of the root user (normally set through Devices)
* ''Linux admin user'': password of the admin user (normally set through Devices)

== Let's Encrypt ==

Configure the certificate creation by Let's Encrypt here.

* ''Enable'': turns the automatic creation on or off
* ''Let's Encrypt App URL'': the URL of your Connector for Let's Encrypt App Service. You can copy&paste this URL from your Connector for Let's Encrypt PBX Manager Plugin
* ''Let's Encrypt App Password'': the client password of your Connector for Let's Encrypt App Service. You can copy&paste this password from your Connector for Let's Encrypt PBX Manager Plugin
* ''Key length'': 2048, 3072 or 4096 (keep in mind, that [[{{NAMESPACE}}:Certificate_management#Certificate_Key_Length_and_CPU_Usage|a higher value provides higher security but also lower performance!]])
* ''DNS Name'': the external DNS names of your device (up to 100 possible)

== Alarms and events ==
* ''URL'': URL to the Events app
* ''Username/Password'': HTTP credentials of the Events app
* ''Email address'': an email address which will get emails on full disk alarms/warnings
* ''Threshold'': All Apps will be stopped and an hourly email sent on reaching this threshold. An alarm is generated 10% before reaching this threshold and an email is sent every 24 hours.

== SMTP ==
SMTP server settings for sending emails from within the AP Manager.

== Replication ==
App Platform [[#App Platform replication|replication settings]]

== Registered Access Domains ==

== Update ==
Updates the App Platform to the latest image available on the App Store.

== Restart ==
Restarts the App Platform.

== Shutdown ==
Shuts down the App Platform.

= App Platform replication =

== Requirements ==

* 13r3 or above on both standby servers and the primary server
* at least an App Platform image starting with version 110002 (otherwise postgresql is too old)
* standby and primary servers must have the same system architecture
** arm gateways (IPx11) just with arm gateways (IPx11)
** arm64 gateways (IPx13) just with arm64 gateways (IPx13)
** x86_64 virtual machines just with x86_64 virtual machines
* the disk size on standby servers must be at least equal as the disk size on the primary server

== General ==
The configuration is done within the App Platform Manager next to the settings button under "Replication".

=== Off ===
No replication is done at all.

=== Primary ===
The App Platform acts as primary server for one or multiple standby servers. 
Max 8 standby servers can be configured. 
 
Every standby server must get a unique name on the primary server which is then also configured on the standby server itself. This is due to the fact, that the primary server preserves data for every standby server while it's not reachable. 
A standby server name must be a valid domain name, although this name is currently not used as DNS name (but might be used in the future). 
 
The password is randomly pregenerated and must be used as handed by the App Platform Manager.

==== PostgreSQL port ====
The default PostgreSQL port is 5432 and can't be changed on the primary. It must be reachable through your firewall or at least forwarded on a different port towards this App Platform on port 5432.

=== Standby ===
Configure the password from the primary and one of the not yet used standby server names. 
The host and port must be reachable through the network. You can specify a non default port which then must be forwarded somewhere else to port 5432 on your primary.

*Note: Do '''not''' configure the same standby name on different standby servers, as this will break the replication on at least one standby! 
*Note: On a standby, all '''locally installed apps are removed''' during installation

== Failure detection ==

The replication state on both primary and standby servers are continuously monitored. 
In case of a broken connection, an alarm is triggered at once and just cleared if the failure goes away. 
 
If such an alarm lasts for 5 minutes an email is send. The recipient address must be configured in the App Platform Manager settings under "Alarms and Events" and you must also provide a valid SMTP configuration.

== Failover ==

There is no automatic failover procedure. If you detect the failure state, you must get active yourself.

=== Standby down ===

Fix the standby server and see if the replication comes up again. If not, setup a new standby server which will replicate the whole database cluster from scratch.

=== Primary down ===

If the primary is down and cannot be brought into life again, you must take the following steps, depending on your configuration:

==== One standby server ====

* Disable the replication in the replication configuration. You will then have a standalone App Platform afterwards.

==== Multiple standby servers ====

* Change the replication type on one of the standby servers from standby to primary. Please note that the other standby entries must still exist here (they are automatically offered)!
* Change the host entry on the other standby servers to the new standby server. The standby server will sync the whole database cluster again, which will take time.

==== Configuration changes ====

You must also tell the PBXes and other tools to use the new primary server.

* You may simply change the IP address behind the DNS of your primary server to point to the new primary server.
**Note: to ensure rapid recognition of the new DNS target, the definition of an appropriate TTL value is recommended
* Without DNS, you must currently modify the configuration by replacing the IP address of the old primary with the new address.
** This must be done in every master PBX configuration.
** This must be done in every App configuration which may use this IP address, e.g. Devices which rolls out an alarm server configuration

== App Platfom update ==

If you're running an active standby server and the major version of the PostgreSQL database didn't change, you can simply update primary and standby servers independently. 
 
If it contains a ''new major version'' of the PostgreSQL database, you must follow these steps:

* deactivate replication on all standby servers (which promotes these standby servers to active servers)
* ensure that the '''same''' App Platform Manager version is running on primary and standby servers!
* perform the App Platform update on the primary server
* perform the App Platform update on the standby servers
* reactivate replication on the standby servers (which will do a full replication again, so it might take some time)

Alternativly you may setup the standby server from scratch directly with the new App Platform image version.

Sadly there is currently no better method offered by PostgreSQL to perform such an upgrade.

See also https://wiki.innovaphone.com/index.php?title=Howto14r2:Firmware_Upgrade_V14r1_V14r2#App_Platform_and_Apps

== Technical backgrounds ==

=== Streaming replication ===

We use the asynchronous [https://www.postgresql.org/docs/9.3/warm-standby.html#STREAMING-REPLICATION streaming replication of PostgreSQL]. A transaction thus just waits for a commit on the primary server. Standby servers will receive the transaction asynchronously afterwards to avoid a reduced writing performance. 
A primary server keeps the neccessary WAL files for every standby server until the standby fetched the neccessary information. 
This fact can lead to higher disk space usage on the primary if one or multiple standby servers are offline for a while.

Take care to fix broken replications as soon as possible to avoid a full disk on the primary server!

=== What is replicated ===
The whole database cluster of an app platform is replicated. This includes every database of every instance and the database of the App Platform Manager itself. 

=== App Services on standbys ===
The database of the App Platform Manager itself also contains the App service binaries to be able to restore applications in a failover case. 
You do not have to install App services on the standby if you install them on the primary. 
App Platform Manager and Webserver can be updated as usual through the App Store or the Devices App if the standby is connected to Devices.

=== App Platform Manager configuration of the standby server ===
The App Platform Manager configuration of the standby server cannot be stored inside the database, as the database is readonly. So it is stored inside a configuration JSON file under ''/home/root/standby.conf''. 
This configuration is backed up as usual by a Devices backup job and can be also manually restored on a standby (not on a primary though!).

Configuration options from the primary are not synced to the standby server, as the standby server has its own configuration (as it could be in a different network etc.)!

=== No automatic failover ===

There is currently no automatic failover mechanism. PostgreSQL doesn't offer multi master replication, so writing is just possible on the primary itself. Standby servers have a readonly database. 
Let's consider the following use case if we would implement an automatic failover with the current technical possibilities: 
* The primary server is connected to a master PBX.
* A slave PBX is also connected to the primary server in another location.
* A standby server is in this location and replicates from the primary.
* The internet connection between primary and standby fails.
* The standby promotes itself to primary, so that the master PBX now writes to the old primary and the slave PBX now writes to the "new" primary.
* The internet connection comes up again and both primary and standby servers now have databases which are out of sync and which cannot be merged.

=== Security ===

* port 5432 must be reachable on the App Platform
* For every standby a PostgreSQL user is created with the REPLICATION role on the primary. Just this user has access to the database server from non localhost connections.
* You cannot establish a standard connection with such a user and modify/read from tables.
* The replication connection is established over TLS by default.

= App Installer PBX Manager Plugin =
== Requirements ==

* V14 and above

== General ==

The app installer plugin allows IT administrator (with access to the PBX Manager) to install/update/delete new apps from the innovaphone app store including Partners apps. It is automatically available with existing app platforms or after adding a new one in the PBX Manager.
It offers a view to the App Platform Manager‘s App Store with all the available functionalities and simplifies the install, update and uninstall of apps.

== Dedicated AP for each user ==

Installing a new app will install the app service and add a new instance with the user’s domain. The instance is automatically started. 
This further enables the configuration of the instance through its respective PBX Manager plugin. 
Uninstalling the app will remove the app service and the corresponding instance.

== Shared AP between users ==

Installing a new app works in a similar way to that of the dedicated AP. However, each time a new user installs the app, only a new instance is created if the app service is already installed. 
A user can uninstall the app, in this case the corresponding instance is deleted. If no more instances exist, then the app service is uninstalled. 
The administrator can only update the app service in such scenario.

= Known Issues =

== Reboot after an image update hangs (ARM gateway) ==

If it happens, that the App Platform doesn't recover after the reboot, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
If '''Kernel command line''' is set to '''/dev/ram0''', the App Platform booted the ramdisk. 
 
Try to fetch the upgrade log file:
https://[APP-PLATFROM-IP/DNS]/manager/ramdisk.log
 
If this doesn't work, try to login with putty in this case (default credentials admin/ipapps and root/iplinux) and issue this command: 
''cat /apps/install_step1.log'' 
 
If this file contains '''finished''' at the end, you can reconfigure the settings under App Platform -> General: 
* press '''Stop'''
* Initrd file: empty
* Kernel command line: '''root=/dev/sda3'''
* Ramdisk size: empty
* press '''Start'''

The App Platform should boot and run the already updated image.

<pre style="color: red; font-size:150%;">---WARNING---
If the file doesn't contain "finished" at the end, you may still need to wait, as an upgrade may take some time!
Do not reconfigure without being sure that the upgrade has finished, otherwise your system may won't run!</pre>

== Reboot after an image update boots always into rescue mode (virtual machine) ==

This most likely means that the image installation didn't finish the first time and was interrupted before the bootloader settings could be changed back to the default partition. 
 
If your App Platform doesn't boot or isn't normally accessible after manual selection of the standard entry in the boot menu, you need to '''revert''' to a '''snapshot/backup''' prior to the update. 
If your App Platform runs normally though, you can follow this instruction to change the default boot entry: 
 
* boot into the '''rescue''' partition
* login with root/iplinux
* edit the file /boot/grub/grub.cfg
** search the line with '''set default=0''' and change it to '''set default=1'''
** reboot

== App Platform doesn't start after an update ==

=== Gateway ===
If it happens, that the App Platform doesn't want to start an update, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
* '''Shutdown''' the App Platform and '''Stop''' it 
* Set '''Kernel command line''' to '''/dev/ram0''' 
* Set '''Initrd file''' to '''ramdisk.ext2.xz''' 
* Set '''Ramdisk size''' to '''100000''' 
* '''Start''' the App Platform now. 

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

Note: This process can take a while, after it's finished it reboots and automatically change the '''Kernel command line''' value.

=== Virtual Machine ===

Boot into the '''rescue''' partition.

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

=== It still doesn't start ===

If it still doesn't start, configure the App Platform to boot from /dev/sda3 (or inside a VM start the second boot loader entry) and login with SSH as root.
Then do a first check to verify that you have a specific error due to an incomplete update or a wrong update order:

* /etc/init.d/S92manager stop
* /apps/manager/manager
* if this outputs '''error while loading shared libraries: libcrypto.so.3:''' you have a manager version which cannot run on the current image.

In this case you must download an older build (14r1 1410593):

* /etc/init.d/S92manager stop
* wget --no-check-certificate -O /apps/manager/manager https://webbuild.innovaphone.com/1410593/arm/manager/manager
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* wget --no-check-certificate -O /apps/webserver/webserver https://webbuild.innovaphone.com/1410593/arm/webserver/webserver
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* chown root:root /apps/manager/manager
* chown root:root /apps/webserver/webserver
* chmod +x /apps/manager/manager
* chmod +x /apps/webserver/webserver
* echo 110000 > /mnt/sda1/label
** this allows the manager to perform an image update again
* /etc/init.d/S92manager start
* now perform an image update and '''afterwards''' update your apps again

== Webserver doesn't respond after an image update ==

If you can't reach the web UI after an image update, please try to connect with SSH as admin user and delete old coredumps, which may prevent the App Platform Manager from starting correctly:
* su root (become root)
* rm -f /mnt/sda2/log/core_dumps/*/*
* /etc/init.d/S92manager restart

Check if you can now reach the App Platform again.

= Tracing =
Each App Service has its own log file, which can be accessed through the Manager App. You can configure a log file size for each App Service. 
Each App Intance has its own trace flags. The following trace flags can be set: 

* Alarm client: used by the manager to send alarms to an alarm server
* App: logs from the App Service itself
* App WebSocket: logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
* AppSharing: just native clients
* AppProxy: just native clients, logs requests which are proxied between the local webserver and the remote server
* Audio: just native clients
* Browser: just native clients
* Command: the command interface is used to execute shell commands, e.g. used by the manager App
* Config: logs config changes of an App
* Database: database logs
* DB files: database file logs
* DNS: DNS request logging
* DTLS: just native clients, DTLS request logging
* Ethernet: interface to get ethernet adapater infos, just manager App
* File: logs for file system access (synchronous), e.g. manager App
* Files: logs for file system access (asynchronous)
* HTTP client: http client logs
* HTTP file: logs for static HTTP files
* ICE: just native clients
* LDS: local domain sockets
* Media: just native clients
* Media channel: just native clients
* Process: IProcess interface logs which is used for spawning, killing processes etc.
* SMTP: SMTP client logs
* TCP: TCP logs
* Time: ITime interface logs
* TLS: TLS logs
* TURN: just native clients
* UDP: UDP logs
* Video: just native clients
* WebSocket client: logs outgoing websocket connections
* Webserver traffic: logs incoming HTTP traffic, which is forwarded from the webserver to the App
* WebDAV service: logs WebDAV requests to the App
* Webserver: enables webserver specific logs

== RPCAP ==

If you open the Manager App, click on the Manager in the left list and then on the Diagnostics button, you can enable RPCAP. 
You can add the interface in wireshark with the string:
rpcap://<APP-Platform-IP>/eth0

'''Please don't forget to disable RPCAP after your testing!'''

= How-Tos =

== How to retrieve files from the App Platform ==
To retrieve files from the App Platform which can not be retrieved via the App Platform manager UI, you can connect to the App Platform using the SCP protocol on port 22. 
 
First copy files to /home/admin as root with Putty or another SSH client:
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''su root'' to be root (''iplinux'' as default password)
 
You can now copy files to ''/home/admin'' (e.g. from /var/log/apps/manager/...). 
 
You can create a tar archive with all logs like this:
* cd /home/admin
* tar -cf - /var/log/* | xz -z - > log.tar.xz
** you may want to exclude coredumps (due to their size):
** tar -cf - --exclude=/var/log/core_dumps/* /var/log/* | xz -z - > log.tar.xz
* chown admin:admin /home/admin/log.tar.xz
 
Then copy the files to your local system, e.g. with WinSCP 
* use ''SCP'' as protocol (NB: WebDAV is not supported on most of the directories on the App Platform )
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''/home/admin'' as start directory
* copy the needed files

== App Platform disk space warning ==

If the configured threshold is reached, all Apps are stopped inside the App Platform . You must then free disk space somehow.

=== Find large instances ===
Click through your apps in the tree on the left side and take a look at the database size of each instance.

=== Delete data inside an instance ===
It depends on the type of app if you can delete data or not. E.g. you can start the Files app and delete files inside this app. 
This won't reclaim disk space though due to the way how PostgreSQL databases work, so you need to follow this guide to reclaim the disk space:

* start the corresponding App
* delete data inside the App
* optimize disk usage of the database by cliking on the button "Clean up database" under Edit instance. If this does not help, continue with the following steps.
* stop the corresponding App again
* download a backup of the instance (backup button at the top), this backup contains the whole instance data, also the password of the instance
* delete this specific instance
* restore the downloaded backup (restore button at the top)

Depending on the hardware and the size of the instance, this process may take hours to complete!

=== Resize the disk ===
The resizing of a disk is just possible for virtual machines, see [[#Resizing the disk of a Virtual machine|Resizing the disk of a Virtual machine]].

=== Delete the whole instance ===
If there is no other possibility, you can delete the whole instance. Afterwards you recreate the instance with the same values and a new random password. Don't forget to set this password in the corresponding PBX App objects though!

=== Restart the Apps or the App Platform ===
If you have enough disk space again, you must either restart the whole App Platform or you manually start all Apps again.

== App Platform/Apps app not online anymore due to full disk ==
If the apps app is not online anymore and you can't access any apps anymore, try to login with an SSH client to see if your disk is full.
Login as admin and afterwards as root (su root). 
 
* issue '''df -h''' and see the disk usage of /dev/sda2, if this is 100%, your disk is too full
* stop the manager
** /etc/init.d/S92manager stop
* empty the 500 MB file, which is exactly for this case here (manager must be 13r1 SR9 or higher to have this file)
** echo "" > /mnt/sda2/empty_if_no_space
* delete log files to recover some space
** rm /var/log/apps/*/*
** rm /var/log/core_dumps/*/*
* restart the postgresql server (see the output if this worked or not)
** /etc/init.d/S50postgresql restart
* restart the manager
** /etc/init.d/S92manager restart
* wait until everything is online again
* open the Apps app and try to find the instance which uses the most disk space and try to delete files/content from it
** you may want to stop all app services first to prevent more writes to the database
** if not possible, you can delete this instance, but you'll loose all data from this instance then!
* after that you can try [[{{NAMESPACE}}:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files|Reference14r2:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files]] to free up space
** If this does not work you can create a backup from the database, delete the database and import the database again.
* free up at least 500 MB so that the manager can create the file again
* delete /mnt/sda2/empty_if_no_space if you are done and restart the manager:
** rm /mnt/sda2/empty_if_no_space
** /etc/init.d/S92manager restart
** the manager restart automatically recreates the empty_if_no_space file if this file doesn't exist

Make sure, that you do '''not''' have backups configured to a local files instance while this files instance is not excluded from backups.
An instance can be excluded from backups in the instance settings in the App Platform Manager.

If all of this doesn't help, you can resize the file system on a VM:
* proceed with [[{{NAMESPACE}}:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine|Reference14r2:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine]]

== Resizing the disk of a Virtual machine ==

Do '''NOT''' resize if you're running an App Platform version higher than '''110000''' and lower than '''110027''' or your data will be lost!
Please update your App Platform to version 110027 or higher before you start resizing your disk.

* stop the VM
* expand the disk using your VM utilities
* start the VM and boot from the first boot entry '''rescue/setup'''
* login with '''root''' and '''iplinux'''
* execute this command: '''/home/root/install_step1.sh log.txt resize'''
* the VM reboots automatically after a successful resize

== Shrink the physically size of PostgreSQL database files ==
Tuples that are deleted in your database are not physically removed from the database-file. So the claimed space on the harddisk is still in use after the delete operation.
If you need to free up some disk space you can force to reorganize the physically database-file on your harddisk.

You can also start this process through the instance settings as long as the App Platform Manager is still running.

'''Important: You are operating on the Database, you have to make a Backup of your Database before you do this!'''

Login via SSH to the APPlatform with the ''admin'' User
su root

=== All databases ===
/etc/init.d/S92manager stop # not always needed, but in case of database errors recommended, of course no app is online then
sudo -u postgres reindexdb -a
sudo -u postgres vacuumdb -a -f
/etc/init.d/S92manager restart # just execute if the manager has been stopped above

=== single database ===
sudo -u postgres reindexdb -d dbname # for a single database with dbname
sudo -u postgres vacuumdb -d dbname -f # for a single database with dbname

Note: This may take some time and the App database is not available during this time

After the process you can check the free dispace via <code>df -h</code>. You can check the claimed space from the database file with the command <code>du -sh /mnt/sda2/pgsql/</code>.

== Change IP Addresses / DNS Names / System Name ==

If you want to change the System Name or the DNS Name of the PBX and/or App Platform Platform you must change records manually '''in the described order'''!
You have to know the Admin password to directly Login to the App Platform .

=== App Platform ===
; Settings - General
* ''Devices app URL''
* ''App platform DNS name''

; Settings - Alarms and Events
* ''URL''

; All Instances
* ''Domain''
* ''Webserver path''

=== PBX ===
Download the configuration and ''search/replace'' in the config file. Upload the config file and reboot.

Manual:
* ''URL'' in all PBX Object (Apps, Voicemail ...)
* [[{{NAMESPACE}}:Gateway/CDR|CDRx]]
* [[{{NAMESPACE}}:PBX/Config/General|IP address for App Platform]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reset Password Page]]
* [[{{NAMESPACE}}:PBX/Config/Authentication|Verification link]]

Depending on your change you have to activate/deactivate the Setting [[{{NAMESPACE}}:PBX/Config/General|Operation without DNS]]

=== Additional Devices / Steps ===
* ''Devices Registration URL''
** There is no automatism to change the URL on all devices in your setup.
** If you have the option to use DHCP, you can temporarily overwrite the [[{{NAMESPACE}}:Services/Update|Update URL]] and execute a [[{{NAMESPACE}}:Concept_Update_Server|custom update script]] to change the ''Device Registration URL''
* ''Alarm server''
* Reverse Proxy configuration
* Change ''Domain Name'' in Devices if you have also changed the system name

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

initial error at 1500329378: ext4_journal_start_sb:328
last error at 1500329378: ext4_journal_start_sb:328

Or you get events like "Broken file system" from your App Platform .

This indicates a file system failure on the Linux Installation.

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

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

=== Gateway ===

* Open the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the Kernel command line from root=/dev/sda3 to root=/dev/ram0
** modify the Initrd file to ramdisk.ext2.xz
** modify the ramdisk size to 100000
** start Linux again
:: This will run Linux on another (hopefully sane) partition.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system

* go back to the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/ram0'' to <code>root=/dev/sda3</code>
** clear the Initrd file field
** clear the ramdisk size field
** start Linux again
:: This will run Linux on the original partition.

=== VM ===

Restart the VM and select the first entry in the boot menu from grub.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system
* Reboot your VM
[[Category:Concept]]

== How to create a memory dump of a running process ==

Sometimes it's usefull to have a memory dump of a running process to investigate certain issues.

* login with SSH and become root
* find out the PID of the relevant process, e.g. with ''ps aux | grep /apps/manager/manager | grep -v grep''
* gdb --pid PID -ex gcore --batch
* this creates a core file core.PID
* download this core file with WinSCP or similar tools

== Move instance database to external database host ==

In case you want to use an external database server instead of the integrated:

* download a backup of the specific instance over the App Platform Manager
* create a postgresql database on the external host:
** createdb --encoding=UTF-8 exampledb
* restore the backup
** pg_restore -d exampledb backup-exampledb.dump
* change the ownership to a specific postgresql user (which you have to create yourself first)
** psql -d postgres -c "ALTER DATABASE exampledb OWNER TO exampleuser"
* configure the database host, name, user and password on the instance inside the App Platform Manager

Reference14r2:Concept App Platform

2025-06-25T07:54:05Z

Dde: /* App Platform - x86-64 (Virtual Machine 64bit) */

= General =
* V13 uses [https://buildroot.org/ buildroot]
* this is an own (innovaphone) collection of packages
* For further information see: [https://buildroot.org/docs.html Buildroot Documentations]

== Requirements ==

* V13 or above
* Gateway (arm): IPx10 (with CF card) or IPx11 (with mSATA SSD)
* Gateway (arm64): IPx13 (with m2 SSD)
* Virtual (x86_64)
** HyperV with [https://docs.microsoft.com/de-de/windows-server/virtualization/hyper-v/deploy/upgrade-virtual-machine-version-in-hyper-v-on-windows-or-windows-server#supported-virtual-machine-configuration-versions VM-configuration Version] 6.2 (minimum: Windows 10 or Windows Server 2016)
** VMWare
** Proxmox/KVM/Qemu

== Default credentials ==

'''During INSTALL, the default passwords are replaced with the global Admin PW!'''
* SSH-Login with '''admin''' and '''ipapps'''
* root login with '''root''' and '''iplinux''' (the root login is not directly possible, you have to login as admin first and use the command ''su root'')
* manager App (web login) '''pwd'''

= App Platform - arm/arm64 (Gateway)=

* The installation image has a size of ~50MB. During installation, the following partitions are created<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 fat32: 200MB (contains ramdisk, rootfs and kernel)
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB

When comparing potential performance of the IPxx11 platform compared to the IPxx10 platform, there are some major differences:
* SSDs found in the xx11 are faster and more reliable than the CF found in the xx10
* the available RAM for the App Platform (as specified in column ''RAM for LAP (GB) out of RAM'' in chapter ''Technical data and recommended number of users supported'' of [[Howto:How to implement large PBXs#Technical data and recommended number of users supported|How to implement large PBXs]]) is factor 6 larger on the xx11 (1,536 GB) than on the xx10 (0,256 GB))
* the xx11 has gigabit Ethernet while the xx10 has 100Mbps Ethernet. The xx10 is therefore not well suited for Apps with larger network traffic, such as Recordings
* the CPU of the xx11 (although it runs on the same frequency) is roughly 20% faster than the xx10

While it is hard to predict the performance of the App Platform in a specific scenario, we see that in a real life environment an App Platform running on an xx11 platform can well support 150 users. The xx10 platform is estimated to support 120 users. Because CPU performance is the limiting factor, larger setups can be built based on the virtual machine platform (see [[#App services and multi-threading|App services and multi-threading]] below).

<references/>

= App Platform - x86-64 (Virtual Machine 64bit) =

* The default disk size is 16GB. It should be increased '''before''' the first start if needed!
* Multiple CPUs are supported, default is one CPU
* default RAM: 512MB
* static IP address, DNS, Gateway can be configured with the command '''setip''' on the console. Run '''setip --help''' to get a list of parameters. (Example: setip --addr=x.x.x.x --mask=x.x.x.x --gateway=x.x.x.x --dns1=x.x.x.x)
* If you have permission problems change to su user (Password is iplinux or your new admin password)
* To figure out your ip address you can use the command: ''ip address'' on the console.
* '''loadkeys de''' can be used to change to german keyboard layout (etc.)
* partitions<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 ext2: 350MB (contains ramdisk, rootfs and kernel)
*** the real partition format size is smaller but there is no need to monitor sda1 as sda1 won't grow during usage of the App Platform
*** sda1 is completely exchanged during an image update and its size might have changed but will never exceed these 350MB
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB
* VMWare Tools: Open VM Tools
* Qemu Guest Agent: installed since 110032
** The qemu guest agent can be configured in Proxmox with ''Virtio'' or ''ISA''. Before version 130012, you '''must''' use '''ISA''', as Virtio was not supported with older versions.

<references/>

= Installation =
==ARM Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-armel.img'' image file.
* The installation runs without any further required step.

==ARM64 Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-arm64.img'' image file.
* The installation runs without any further required step.

==Virtual machine==

* Import the image into your server environment.
** Proxmox: follow this description here, just with the app-platform-ova.zip: https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Proxmox_VE
* Edit the disk size, if needed.
* Start the machine and wait until it reboots and starts again.
* Note: If you need to access an IP addresses available through a VPN connection from from inside the virtual machine, it could be that you need to set the network of your VM to NAT (and also add the URL for an IP to /etc/hosts)

[https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Configuration More Configuration Hints regarding VM Ware]

== Backup of the Apps ==

Each App Service can have multiple instances and each instance has its own database. The manager app itself also has its own database. 
There are no other files which need to be backuped. 
The standard way to backup the databases is through the Devices App [[{{NAMESPACE}}:Concept_App_Service_Devices#Backups]]. 
 
An alternate way is to use a command file which is similar to the command files from the firmware.

===Commands===
* '''times''' 0,12 # backup only at 0 or 12 o'clock
* '''backup-instances''' http://user:pw@ip/path/#I-#D.dump PUT
** PUT and POST are supported, all instances including the manager itself are saved
* '''backup-instance''' http://user:pw@ip/path/#I-#D.dump apidemo example.com PUT
** backup a single instance with instance name and instance domain
* '''backup-manager''' http://user:pw@ip/path/#I-#D.dump

===Hash parameters===
* #L App Platform label (neu), e.g. 10024
* #A App label (neu), e.g. 130004
* #I instance name (neu), e.g. reporting1
* #D instance domain (neu), e.g. innovaphone.com
* #m MAC address of the LAP, e.g. 00ab11eeff
* #d Current date and time (plain UTC without daylight saving and timezone adjustments) 20051010-170130
* #bn rolling backup index (n >=0 and <= 9, just one digit)
* ## escapes a hash mark

= App Platform Infrastructure and Concept =
== Webserver ==
The app platform includes a webserver that is highly optimized for handling many Websocket connections at a low memory footprint.
All apps use that webserver by registering for specific HTTP subpath. So they can all use the same HTTP/HTTPS ports - typically the standard ports.

=== Import Custom SSL Certificate ===
You have to upload a PEM Certificate with the following chain structure and without password encoding.

-----BEGIN CERTIFICATE-----
(certificate: eg. your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: eg. DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: eg. TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: eg. your_domain_name.key)
-----END RSA PRIVATE KEY-----

If you have problems generating the complete and correct certificate chain, you can use tools such as https://whatsmychaincert.com/ as an aid.
'''Please keep in mind that you never give away the private part of your key.'''

=== Known issues ===
*The app platform webserver can use only the default http/https ports 80/443.
*By design, there is no possibility to restore the default webserver certificate on the App Platform, if another certificate was once uploaded. 
**If nevertheless needed, you must login with Putty (see [[#How to retrieve files from the AP| Retrieve files]]) and execute these commands as root:
**''psql -d manager -c "DELETE FROM config WHERE name='webserverCertificate'"''
**''/etc/init.d/S92manager restart''
*The app platform webserver interprets URLs case-sensitive. In other words, <nowiki>http://<addr>/file.txt</nowiki> is not the same as <nowiki>http://<addr>/FILE.TXT</nowiki>

== Database ==
The app platform creates a database for each app instance with a given password. In the installer there will be used randomly generated passwords. You can set a new database password for every instance in the Application Platform.

The apps should store all data in that database. That makes sure that a consistent backup and restore of app instances can be done by the app platform manager.
In hosted scenarios, having separate databases for each instance also makes sure that the data of different customers are clearly separated and can easily be moved from one physical platform to another.

The default configuration decline database request from extern. If you need external access you can change the PGSQL configuration (as root) in the file ''/mnt/sda2/pgsql/pg_hba.conf''.
After editing pg_hba.conf, the database-service has to be restarted with the command <code>/etc/init.d/S50postgresql restart</code>
(Please think about it before you do it, because a better way is to create your own local app with local database access.)

You can find the official documentation for the pg_hba.conf here: https://www.postgresql.org/docs/14/auth-pg-hba-conf.html

Please note that you do this on your own responsibility, that it makes sense to create a backup of the original pg_hba.conf
and that you may break your database server if you do not know exactly what you do!

Sometimes the Apps are not proper working after this. You can wait a while until everything is working again or you go the hard way:
* stop the manager
** <code>/etc/init.d/S92manager stop</code>
* restart the database-service (maybe not really necessary, but makes a good feeling)
**<code>/etc/init.d/S50postgresql restart</code>
* start the manager
** <code>/etc/init.d/S92manager start</code>

=== Nightly database analyse ===

Every database is analysed at night to keep indexes in sync with the data. This triggers a ''vacuumdb -a -z'', which updates optimizer statistics, but does '''not''' shrink the physical size of the database. 
This must be done manually in the instance settings.

== App Platform Manager ==
The App Platform Manager is the central component of the App Platform. It does the following:
* Installing app services by downloading the binaries from an app store.
* Running and monitoring app services. If an app service crashes it is restarted, automatically.
* Management of app instances and providing them with the environment they need:
** A database
** A webserver path
** A password for authentication
* Backup and restore of app instances.
* Collecting debug information like tracing and crash dumps.
* System monitoring (CPU usage, memory usage, etc).

== App Services ==
App services are runned by the App Platform Manager. They implement an interface that is used by the manager to start, stop and configure app instances. Each service runs in a separate child process of the manager.

== App Instances ==
The actual functionality of an app service is provided by app instances. They run in the same process as the app service but have a distinct webserver path and their own database. There can be 0..n instances of an app service. Instances can optionally host (web) apps that can be opened in the myApps client.

Each instance of an App service has two passwords. The instance password itself and a database password. If you want to change it you must update the password on both sides. 
The instance password must match to the password in the corresponding PBX App objects, while one instance can have different App objects. 
The database password must be just known to the manager and not outside of the App Platform.

The ''Database name'' and ''Database user'' are both limited to a length of 63 characters. By default, the App Manager would create ''<domain>''_''<instance-name>'' as value for both. This is why it is recommended to use instance names so that length(name) + length(domain) is less than 63 characters. However, if this is not possible, you can manually shorten the suggested values (both must still be unique on your App Platform).

=== Cleanup database ===
You can cleanup the instance database inside the instance settings. This starts the vacuumdb process for the instance database which frees disk space of deleted rows.
Note that this process locks the database and that sufficient disk space is needed to complete it!

=== External database host ===
You can optionally configure an external database host, if the database shall be hosted on an external host. 
Note that the App Platform Manager still creates a local database, which is then not used as long as the external host is configured.

What are external databases useful for?:
* User data is too large (files are stored as BLOB in the database)
* Other (non-innovaphone) database servers are to be used due to other regulations
* There is already an external database cluster with its own backup/restore processes which should be used
* More performance is required (please note that a local UNIX socket provides much faster results than a remote database server). Depending on the app and the task of the app, it can still be useful to use a separate server if it is faster.

==== Supported database types ====
In principle, ''PostgreSQL'' and ''MySQL'' are supported. However, please note that the respective app must be designed for the target database server type. If an app has been developed for PostgreSQL, it cannot be operated on a MySQL server.

'''Please note:''' All innovaphone apps are developed exclusively as PostgreSQL apps.

MySQL therefore only makes sense if own apps are developed and MySQL or certain MySQL features are to be used. For such apps, it is very important to deactivate the automatic Application Platform APP-Backup.
The database backup process of the App Platform uses PostgreSQL backup commands, which is why the backup would fail, so the app must be excluded from the backup, and you must take care of the backup yourself.

==== Database creation ====
If you use an external database, you have to create the database itself.
The App Platform Manager itself creates a PostgreSQL database like this (you may respect this on your database host to be compatible with the database implementation inside the Apps):
* CREATE DATABASE "dbname" ENCODING 'UTF8';
* CREATE USER "dbuser";
* ALTER USER "dbuser" WITH PASSWORD 'dbpassword';
* GRANT ALL PRIVILEGES ON DATABASE "dbname" TO "dbuser";
* ALTER DATABASE "dbname" OWNER TO "dbuser";
* REVOKE CONNECT ON DATABASE "dbname" FROM public;

==== Database connection ====
There are different possibilities to specify the host. You can use a DNS-Name, IPv4 or IPv6. A port can be optionally added with a colon.

Our PostgreSQL implementation sets sslmode=prefer, so SSL is used by default if enabled on the server.

==== Backup/Restore ====
External databases are still backuped as normal, but you can't restore such a database with the App Platform Manager on the external host! You must restore such a dump manually on your database host.

==== Database redundancy ====
In principle, it is possible to create redundancies for failure scenarios through this function.

However, there are different scenarios that need to be evaluated on a case-by-case basis:

* One database, multiple App Platforms (primary online / secondary '''offline''') where multiple apps access the same database.
** This mode of operation is legal as long as you can really ensure that only one App Platform is active at a time.

* One database, multiple App Platforms (primary online / secondary '''online''') with multiple apps accessing the same database.
** This operating mode cannot be used for innovaphone apps, as the app itself would have to be developed for such a mode, which it is not.

However, we advise great caution here! The use of the same databases from different nodes may only be used if you can ensure that the databases or runtime environments of apps cannot get into a ''split-brain'' mode.

== Relationship between app instances and app objects in the PBX ==
Typically an app instance is connected to one or more app objects in a customer PBX. This is done by configuring the same parameters on both sides:
* URL
* Password
The password is used by the PBX for authenticating itself, users and services against the app instance.

Some apps need a websocket connection with the PBX. When "websocket" is activated at the app object, the PBX establishes a websocket connection to the app instance and provides the APIs that are configured at the app object.

=== Supported scenarios ===
It is important to understand that the concept does not do any assumptions on how PBXes and APs are correlated. So you can have
* One App Platform for one customer
* One App Platform for many customers
* Many App Platforms for one customer
* Many App Platforms for many customers

Attention: The V13 installer can only configure the scenario "''One App Platform for one customer''". If you want to have a different scenario, you have to configure it manually.

For hosting or cloud scenarios you need special scenarios. Please refer our [[Howto:V13 Hosting| V13 Hosting]] instructions.

=== Restrictions ===
Currently we don't have redundancy for app instances or App Platforms.

== Update of the App Platform itself ==
The App Platform is build on top of buildroot and will receive updates and fixes from time to time. 
You can update the used build inside the Manager App by using the '''Update''' button at the top. 

It is strongly advised to make a full backup (VM) or at least backup all apps (Gateway) before you run such an update!

After the update has been downloaded and verified, your App Platform will reboot.
You can check the installation process after the reboot with the following URL: https://IP-of-AP/manager/ramdisk.log

== App services and multi-threading ==
Each App Service runs in a single process with no multi-threading, independent of the instances of the App Service. However, each instance maintains its own database connection and the database responds to this connect with the creation of a new process. Each app service therefore uses 1+''n'' threads (where ''n'' is the number of instances). All communication between app service instances and their clients must pass the single-threaded web server. On platforms with multi-threading support (i.e. VMware or Hyper-V), up to 1 + ''m'' + ''m'' * ''n'' (with ''m'' being the number of Apps and ''n'' the number of instances per App) threads can be utilized.

= AP Manager settings =

== General ==
* ''Enable Developer mode'': in developer mode, apps can be manually uploaded without an App Store
* ''Disable App security'': each App has an own unix user and if this flag is set, the user can login with SSH for debugging
* ''App Store URL'': the URL to the App Store where Apps are searched and also an update of the AP image itself
* ''Devices app URL'': the URL to the Devices App to manage the AP through Devices
* ''Devices app URL 2'': don't use!
* ''App Platform DNS name'': currently not used
* ''NTP server 1/2'': NTP servers for this AP (in addition to NTP servers retrieved by DHCP)
* ''Timezone string'': A timezone string which is used by the App Platform Manager to do certain jobs according to the configured timezone.
** Note that this doesn't change the timezone of the linux itself!
* ''DNS server 1/2'': DNS servers for this AP (in addition to DNS servers retrieved by DHCP)
* ''Database optimization time'': The database optimization process will be started at this hour (local time), with a random offset of up to 7 hours
* ''Command file'': obsolete, use the Devices App for backups!

== Security ==
* ''Current Webserver certificates'': shows the current certificates with the ability to download them.
* ''Webserver certificate'': upload a webserver certificate in PEM format
* ''AP Manager password'': the password to the web interface of the AP Manager (normally set through Devices)
* ''Linux root user'': password of the root user (normally set through Devices)
* ''Linux admin user'': password of the admin user (normally set through Devices)

== Let's Encrypt ==

Configure the certificate creation by Let's Encrypt here.

* ''Enable'': turns the automatic creation on or off
* ''Let's Encrypt App URL'': the URL of your Connector for Let's Encrypt App Service. You can copy&paste this URL from your Connector for Let's Encrypt PBX Manager Plugin
* ''Let's Encrypt App Password'': the client password of your Connector for Let's Encrypt App Service. You can copy&paste this password from your Connector for Let's Encrypt PBX Manager Plugin
* ''Key length'': 2048, 3072 or 4096 (keep in mind, that [[{{NAMESPACE}}:Certificate_management#Certificate_Key_Length_and_CPU_Usage|a higher value provides higher security but also lower performance!]])
* ''DNS Name'': the external DNS names of your device (up to 100 possible)

== Alarms and events ==
* ''URL'': URL to the Events app
* ''Username/Password'': HTTP credentials of the Events app
* ''Email address'': an email address which will get emails on full disk alarms/warnings
* ''Threshold'': All Apps will be stopped and an hourly email sent on reaching this threshold. An alarm is generated 10% before reaching this threshold and an email is sent every 24 hours.

== SMTP ==
SMTP server settings for sending emails from within the AP Manager.

== Replication ==
App Platform [[#App Platform replication|replication settings]]

== Registered Access Domains ==

== Update ==
Updates the App Platform to the latest image available on the App Store.

== Restart ==
Restarts the App Platform.

== Shutdown ==
Shuts down the App Platform.

= App Platform replication =

== Requirements ==

* 13r3 or above on both standby servers and the primary server
* at least an App Platform image starting with version 110002 (otherwise postgresql is too old)
* standby and primary servers must have the same system architecture
** arm gateways (IPx11) just with arm gateways (IPx11)
** arm64 gateways (IPx13) just with arm64 gateways (IPx13)
** x86_64 virtual machines just with x86_64 virtual machines
* the disk size on standby servers must be at least equal as the disk size on the primary server

== General ==
The configuration is done within the App Platform Manager next to the settings button under "Replication".

=== Off ===
No replication is done at all.

=== Primary ===
The App Platform acts as primary server for one or multiple standby servers. 
Max 8 standby servers can be configured. 
 
Every standby server must get a unique name on the primary server which is then also configured on the standby server itself. This is due to the fact, that the primary server preserves data for every standby server while it's not reachable. 
A standby server name must be a valid domain name, although this name is currently not used as DNS name (but might be used in the future). 
 
The password is randomly pregenerated and must be used as handed by the App Platform Manager.

==== PostgreSQL port ====
The default PostgreSQL port is 5432 and can't be changed on the primary. It must be reachable through your firewall or at least forwarded on a different port towards this App Platform on port 5432.

=== Standby ===
Configure the password from the primary and one of the not yet used standby server names. 
The host and port must be reachable through the network. You can specify a non default port which then must be forwarded somewhere else to port 5432 on your primary.

*Note: Do '''not''' configure the same standby name on different standby servers, as this will break the replication on at least one standby! 
*Note: On a standby, all '''locally installed apps are removed''' during installation

== Failure detection ==

The replication state on both primary and standby servers are continuously monitored. 
In case of a broken connection, an alarm is triggered at once and just cleared if the failure goes away. 
 
If such an alarm lasts for 5 minutes an email is send. The recipient address must be configured in the App Platform Manager settings under "Alarms and Events" and you must also provide a valid SMTP configuration.

== Failover ==

There is no automatic failover procedure. If you detect the failure state, you must get active yourself.

=== Standby down ===

Fix the standby server and see if the replication comes up again. If not, setup a new standby server which will replicate the whole database cluster from scratch.

=== Primary down ===

If the primary is down and cannot be brought into life again, you must take the following steps, depending on your configuration:

==== One standby server ====

* Disable the replication in the replication configuration. You will then have a standalone App Platform afterwards.

==== Multiple standby servers ====

* Change the replication type on one of the standby servers from standby to primary. Please note that the other standby entries must still exist here (they are automatically offered)!
* Change the host entry on the other standby servers to the new standby server. The standby server will sync the whole database cluster again, which will take time.

==== Configuration changes ====

You must also tell the PBXes and other tools to use the new primary server.

* You may simply change the IP address behind the DNS of your primary server to point to the new primary server.
**Note: to ensure rapid recognition of the new DNS target, the definition of an appropriate TTL value is recommended
* Without DNS, you must currently modify the configuration by replacing the IP address of the old primary with the new address.
** This must be done in every master PBX configuration.
** This must be done in every App configuration which may use this IP address, e.g. Devices which rolls out an alarm server configuration

== App Platfom update ==

If you're running an active standby server and the major version of the PostgreSQL database didn't change, you can simply update primary and standby servers independently. 
 
If it contains a ''new major version'' of the PostgreSQL database, you must follow these steps:

* deactivate replication on all standby servers (which promotes these standby servers to active servers)
* ensure that the '''same''' App Platform Manager version is running on primary and standby servers!
* perform the App Platform update on the primary server
* perform the App Platform update on the standby servers
* reactivate replication on the standby servers (which will do a full replication again, so it might take some time)

Alternativly you may setup the standby server from scratch directly with the new App Platform image version.

Sadly there is currently no better method offered by PostgreSQL to perform such an upgrade.

See also https://wiki.innovaphone.com/index.php?title=Howto14r2:Firmware_Upgrade_V14r1_V14r2#App_Platform_and_Apps

== Technical backgrounds ==

=== Streaming replication ===

We use the asynchronous [https://www.postgresql.org/docs/9.3/warm-standby.html#STREAMING-REPLICATION streaming replication of PostgreSQL]. A transaction thus just waits for a commit on the primary server. Standby servers will receive the transaction asynchronously afterwards to avoid a reduced writing performance. 
A primary server keeps the neccessary WAL files for every standby server until the standby fetched the neccessary information. 
This fact can lead to higher disk space usage on the primary if one or multiple standby servers are offline for a while.

Take care to fix broken replications as soon as possible to avoid a full disk on the primary server!

=== What is replicated ===
The whole database cluster of an app platform is replicated. This includes every database of every instance and the database of the App Platform Manager itself. 

=== App Services on standbys ===
The database of the App Platform Manager itself also contains the App service binaries to be able to restore applications in a failover case. 
You do not have to install App services on the standby if you install them on the primary. 
App Platform Manager and Webserver can be updated as usual through the App Store or the Devices App if the standby is connected to Devices.

=== App Platform Manager configuration of the standby server ===
The App Platform Manager configuration of the standby server cannot be stored inside the database, as the database is readonly. So it is stored inside a configuration JSON file under ''/home/root/standby.conf''. 
This configuration is backed up as usual by a Devices backup job and can be also manually restored on a standby (not on a primary though!).

Configuration options from the primary are not synced to the standby server, as the standby server has its own configuration (as it could be in a different network etc.)!

=== No automatic failover ===

There is currently no automatic failover mechanism. PostgreSQL doesn't offer multi master replication, so writing is just possible on the primary itself. Standby servers have a readonly database. 
Let's consider the following use case if we would implement an automatic failover with the current technical possibilities: 
* The primary server is connected to a master PBX.
* A slave PBX is also connected to the primary server in another location.
* A standby server is in this location and replicates from the primary.
* The internet connection between primary and standby fails.
* The standby promotes itself to primary, so that the master PBX now writes to the old primary and the slave PBX now writes to the "new" primary.
* The internet connection comes up again and both primary and standby servers now have databases which are out of sync and which cannot be merged.

=== Security ===

* port 5432 must be reachable on the App Platform
* For every standby a PostgreSQL user is created with the REPLICATION role on the primary. Just this user has access to the database server from non localhost connections.
* You cannot establish a standard connection with such a user and modify/read from tables.
* The replication connection is established over TLS by default.

= App Installer PBX Manager Plugin =
== Requirements ==

* V14 and above

== General ==

The app installer plugin allows IT administrator (with access to the PBX Manager) to install/update/delete new apps from the innovaphone app store including Partners apps. It is automatically available with existing app platforms or after adding a new one in the PBX Manager.
It offers a view to the App Platform Manager‘s App Store with all the available functionalities and simplifies the install, update and uninstall of apps.

== Dedicated AP for each user ==

Installing a new app will install the app service and add a new instance with the user’s domain. The instance is automatically started. 
This further enables the configuration of the instance through its respective PBX Manager plugin. 
Uninstalling the app will remove the app service and the corresponding instance.

== Shared AP between users ==

Installing a new app works in a similar way to that of the dedicated AP. However, each time a new user installs the app, only a new instance is created if the app service is already installed. 
A user can uninstall the app, in this case the corresponding instance is deleted. If no more instances exist, then the app service is uninstalled. 
The administrator can only update the app service in such scenario.

= Known Issues =

== Reboot after an image update hangs (ARM gateway) ==

If it happens, that the App Platform doesn't recover after the reboot, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
If '''Kernel command line''' is set to '''/dev/ram0''', the App Platform booted the ramdisk. 
 
Try to fetch the upgrade log file:
https://[APP-PLATFROM-IP/DNS]/manager/ramdisk.log
 
If this doesn't work, try to login with putty in this case (default credentials admin/ipapps and root/iplinux) and issue this command: 
''cat /apps/install_step1.log'' 
 
If this file contains '''finished''' at the end, you can reconfigure the settings under App Platform -> General: 
* press '''Stop'''
* Initrd file: empty
* Kernel command line: '''root=/dev/sda3'''
* Ramdisk size: empty
* press '''Start'''

The App Platform should boot and run the already updated image.

<pre style="color: red; font-size:150%;">---WARNING---
If the file doesn't contain "finished" at the end, you may still need to wait, as an upgrade may take some time!
Do not reconfigure without being sure that the upgrade has finished, otherwise your system may won't run!</pre>

== Reboot after an image update boots always into rescue mode (virtual machine) ==

This most likely means that the image installation didn't finish the first time and was interrupted before the bootloader settings could be changed back to the default partition. 
 
If your App Platform doesn't boot or isn't normally accessible after manual selection of the standard entry in the boot menu, you need to '''revert''' to a '''snapshot/backup''' prior to the update. 
If your App Platform runs normally though, you can follow this instruction to change the default boot entry: 
 
* boot into the '''rescue''' partition
* login with root/iplinux
* edit the file /boot/grub/grub.cfg
** search the line with '''set default=0''' and change it to '''set default=1'''
** reboot

== App Platform doesn't start after an update ==

=== Gateway ===
If it happens, that the App Platform doesn't want to start an update, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
* '''Shutdown''' the App Platform and '''Stop''' it 
* Set '''Kernel command line''' to '''/dev/ram0''' 
* Set '''Initrd file''' to '''ramdisk.ext2.xz''' 
* Set '''Ramdisk size''' to '''100000''' 
* '''Start''' the App Platform now. 

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

Note: This process can take a while, after it's finished it reboots and automatically change the '''Kernel command line''' value.

=== Virtual Machine ===

Boot into the '''rescue''' partition.

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

=== It still doesn't start ===

If it still doesn't start, configure the App Platform to boot from /dev/sda3 (or inside a VM start the second boot loader entry) and login with SSH as root.
Then do a first check to verify that you have a specific error due to an incomplete update or a wrong update order:

* /etc/init.d/S92manager stop
* /apps/manager/manager
* if this outputs '''error while loading shared libraries: libcrypto.so.3:''' you have a manager version which cannot run on the current image.

In this case you must download an older build (14r1 1410593):

* /etc/init.d/S92manager stop
* wget --no-check-certificate -O /apps/manager/manager https://webbuild.innovaphone.com/1410593/arm/manager/manager
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* wget --no-check-certificate -O /apps/webserver/webserver https://webbuild.innovaphone.com/1410593/arm/webserver/webserver
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* chown root:root /apps/manager/manager
* chown root:root /apps/webserver/webserver
* chmod +x /apps/manager/manager
* chmod +x /apps/webserver/webserver
* echo 110000 > /mnt/sda1/label
** this allows the manager to perform an image update again
* /etc/init.d/S92manager start
* now perform an image update and '''afterwards''' update your apps again

== Webserver doesn't respond after an image update ==

If you can't reach the web UI after an image update, please try to connect with SSH as admin user and delete old coredumps, which may prevent the App Platform Manager from starting correctly:
* su root (become root)
* rm -f /mnt/sda2/log/core_dumps/*/*
* /etc/init.d/S92manager restart

Check if you can now reach the App Platform again.

= Tracing =
Each App Service has its own log file, which can be accessed through the Manager App. You can configure a log file size for each App Service. 
Each App Intance has its own trace flags. The following trace flags can be set: 

* Alarm client: used by the manager to send alarms to an alarm server
* App: logs from the App Service itself
* App WebSocket: logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
* AppSharing: just native clients
* AppProxy: just native clients, logs requests which are proxied between the local webserver and the remote server
* Audio: just native clients
* Browser: just native clients
* Command: the command interface is used to execute shell commands, e.g. used by the manager App
* Config: logs config changes of an App
* Database: database logs
* DB files: database file logs
* DNS: DNS request logging
* DTLS: just native clients, DTLS request logging
* Ethernet: interface to get ethernet adapater infos, just manager App
* File: logs for file system access (synchronous), e.g. manager App
* Files: logs for file system access (asynchronous)
* HTTP client: http client logs
* HTTP file: logs for static HTTP files
* ICE: just native clients
* LDS: local domain sockets
* Media: just native clients
* Media channel: just native clients
* Process: IProcess interface logs which is used for spawning, killing processes etc.
* SMTP: SMTP client logs
* TCP: TCP logs
* Time: ITime interface logs
* TLS: TLS logs
* TURN: just native clients
* UDP: UDP logs
* Video: just native clients
* WebSocket client: logs outgoing websocket connections
* Webserver traffic: logs incoming HTTP traffic, which is forwarded from the webserver to the App
* WebDAV service: logs WebDAV requests to the App
* Webserver: enables webserver specific logs

== RPCAP ==

If you open the Manager App, click on the Manager in the left list and then on the Diagnostics button, you can enable RPCAP. 
You can add the interface in wireshark with the string:
rpcap://<APP-Platform-IP>/eth0

'''Please don't forget to disable RPCAP after your testing!'''

= How-Tos =

== How to retrieve files from the App Platform ==
To retrieve files from the App Platform which can not be retrieved via the App Platform manager UI, you can connect to the App Platform using the SCP protocol on port 22. 
 
First copy files to /home/admin as root with Putty or another SSH client:
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''su root'' to be root (''iplinux'' as default password)
 
You can now copy files to ''/home/admin'' (e.g. from /var/log/apps/manager/...). 
 
You can create a tar archive with all logs like this:
* cd /home/admin
* tar -cf - /var/log/* | xz -z - > log.tar.xz
** you may want to exclude coredumps (due to their size):
** tar -cf - --exclude=/var/log/core_dumps/* /var/log/* | xz -z - > log.tar.xz
* chown admin:admin /home/admin/log.tar.xz
 
Then copy the files to your local system, e.g. with WinSCP 
* use ''SCP'' as protocol (NB: WebDAV is not supported on most of the directories on the App Platform )
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''/home/admin'' as start directory
* copy the needed files

== App Platform disk space warning ==

If the configured threshold is reached, all Apps are stopped inside the App Platform . You must then free disk space somehow.

=== Find large instances ===
Click through your apps in the tree on the left side and take a look at the database size of each instance.

=== Delete data inside an instance ===
It depends on the type of app if you can delete data or not. E.g. you can start the Files app and delete files inside this app. 
This won't reclaim disk space though due to the way how PostgreSQL databases work, so you need to follow this guide to reclaim the disk space:

* start the corresponding App
* delete data inside the App
* optimize disk usage of the database by cliking on the button "Clean up database" under Edit instance. If this does not help, continue with the following steps.
* stop the corresponding App again
* download a backup of the instance (backup button at the top), this backup contains the whole instance data, also the password of the instance
* delete this specific instance
* restore the downloaded backup (restore button at the top)

Depending on the hardware and the size of the instance, this process may take hours to complete!

=== Resize the disk ===
The resizing of a disk is just possible for virtual machines, see [[#Resizing the disk of a Virtual machine|Resizing the disk of a Virtual machine]].

=== Delete the whole instance ===
If there is no other possibility, you can delete the whole instance. Afterwards you recreate the instance with the same values and a new random password. Don't forget to set this password in the corresponding PBX App objects though!

=== Restart the Apps or the App Platform ===
If you have enough disk space again, you must either restart the whole App Platform or you manually start all Apps again.

== App Platform/Apps app not online anymore due to full disk ==
If the apps app is not online anymore and you can't access any apps anymore, try to login with an SSH client to see if your disk is full.
Login as admin and afterwards as root (su root). 
 
* issue '''df -h''' and see the disk usage of /dev/sda2, if this is 100%, your disk is too full
* stop the manager
** /etc/init.d/S92manager stop
* empty the 500 MB file, which is exactly for this case here (manager must be 13r1 SR9 or higher to have this file)
** echo "" > /mnt/sda2/empty_if_no_space
* delete log files to recover some space
** rm /var/log/apps/*/*
** rm /var/log/core_dumps/*/*
* restart the postgresql server (see the output if this worked or not)
** /etc/init.d/S50postgresql restart
* restart the manager
** /etc/init.d/S92manager restart
* wait until everything is online again
* open the Apps app and try to find the instance which uses the most disk space and try to delete files/content from it
** you may want to stop all app services first to prevent more writes to the database
** if not possible, you can delete this instance, but you'll loose all data from this instance then!
* after that you can try [[{{NAMESPACE}}:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files|Reference14r2:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files]] to free up space
** If this does not work you can create a backup from the database, delete the database and import the database again.
* free up at least 500 MB so that the manager can create the file again
* delete /mnt/sda2/empty_if_no_space if you are done and restart the manager:
** rm /mnt/sda2/empty_if_no_space
** /etc/init.d/S92manager restart
** the manager restart automatically recreates the empty_if_no_space file if this file doesn't exist

Make sure, that you do '''not''' have backups configured to a local files instance while this files instance is not excluded from backups.
An instance can be excluded from backups in the instance settings in the App Platform Manager.

If all of this doesn't help, you can resize the file system on a VM:
* proceed with [[{{NAMESPACE}}:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine|Reference14r2:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine]]

== Resizing the disk of a Virtual machine ==

Do '''NOT''' resize if you're running an App Platform version higher than '''110000''' and lower than '''110027''' or your data will be lost!
Please update your App Platform to version 110027 or higher before you start resizing your disk.

* stop the VM
* expand the disk using your VM utilities
* start the VM and boot from the first boot entry '''rescue/setup'''
* login with '''root''' and '''iplinux'''
* execute this command: '''/home/root/install_step1.sh log.txt resize'''
* the VM reboots automatically after a successful resize

== Shrink the physically size of PostgreSQL database files ==
Tuples that are deleted in your database are not physically removed from the database-file. So the claimed space on the harddisk is still in use after the delete operation.
If you need to free up some disk space you can force to reorganize the physically database-file on your harddisk.

You can also start this process through the instance settings as long as the App Platform Manager is still running.

'''Important: You are operating on the Database, you have to make a Backup of your Database before you do this!'''

Login via SSH to the APPlatform with the ''admin'' User
su root

=== All databases ===
/etc/init.d/S92manager stop # not always needed, but in case of database errors recommended, of course no app is online then
sudo -u postgres reindexdb -a
sudo -u postgres vacuumdb -a -f
/etc/init.d/S92manager restart # just execute if the manager has been stopped above

=== single database ===
sudo -u postgres reindexdb -d dbname # for a single database with dbname
sudo -u postgres vacuumdb -d dbname -f # for a single database with dbname

Note: This may take some time and the App database is not available during this time

After the process you can check the free dispace via <code>df -h</code>. You can check the claimed space from the database file with the command <code>du -sh /mnt/sda2/pgsql/</code>.

== Change IP Addresses / DNS Names / System Name ==

If you want to change the System Name or the DNS Name of the PBX and/or App Platform Platform you must change records manually '''in the described order'''!
You have to know the Admin password to directly Login to the App Platform .

=== App Platform ===
; Settings - General
* ''Devices app URL''
* ''App platform DNS name''

; Settings - Alarms and Events
* ''URL''

; All Instances
* ''Domain''
* ''Webserver path''

=== PBX ===
Download the configuration and ''search/replace'' in the config file. Upload the config file and reboot.

Manual:
* ''URL'' in all PBX Object (Apps, Voicemail ...)
* [[{{NAMESPACE}}:Gateway/CDR|CDRx]]
* [[{{NAMESPACE}}:PBX/Config/General|IP address for App Platform]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reset Password Page]]
* [[{{NAMESPACE}}:PBX/Config/Authentication|Verification link]]

Depending on your change you have to activate/deactivate the Setting [[{{NAMESPACE}}:PBX/Config/General|Operation without DNS]]

=== Additional Devices / Steps ===
* ''Devices Registration URL''
** There is no automatism to change the URL on all devices in your setup.
** If you have the option to use DHCP, you can temporarily overwrite the [[{{NAMESPACE}}:Services/Update|Update URL]] and execute a [[{{NAMESPACE}}:Concept_Update_Server|custom update script]] to change the ''Device Registration URL''
* ''Alarm server''
* Reverse Proxy configuration
* Change ''Domain Name'' in Devices if you have also changed the system name

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

initial error at 1500329378: ext4_journal_start_sb:328
last error at 1500329378: ext4_journal_start_sb:328

Or you get events like "Broken file system" from your App Platform .

This indicates a file system failure on the Linux Installation.

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

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

=== Gateway ===

* Open the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the Kernel command line from root=/dev/sda3 to root=/dev/ram0
** modify the Initrd file to ramdisk.ext2.xz
** modify the ramdisk size to 100000
** start Linux again
:: This will run Linux on another (hopefully sane) partition.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system

* go back to the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/ram0'' to <code>root=/dev/sda3</code>
** clear the Initrd file field
** clear the ramdisk size field
** start Linux again
:: This will run Linux on the original partition.

=== VM ===

Restart the VM and select the first entry in the boot menu from grub.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system
* Reboot your VM
[[Category:Concept]]

== How to create a memory dump of a running process ==

Sometimes it's usefull to have a memory dump of a running process to investigate certain issues.

* login with SSH and become root
* find out the PID of the relevant process, e.g. with ''ps aux | grep /apps/manager/manager | grep -v grep''
* gdb --pid PID -ex gcore --batch
* this creates a core file core.PID
* download this core file with WinSCP or similar tools

== Move instance database to external database host ==

In case you want to use an external database server instead of the integrated:

* download a backup of the specific instance over the App Platform Manager
* create a postgresql database on the external host:
** createdb --encoding=UTF-8 exampledb
* restore the backup
** pg_restore -d exampledb backup-exampledb.dump
* change the ownership to a specific postgresql user (which you have to create yourself first)
** psql -d postgres -c "ALTER DATABASE exampledb OWNER TO exampleuser"
* configure the database host, name, user and password on the instance inside the App Platform Manager

Reference14r2:Concept App Platform

2025-05-27T11:11:12Z

Dde: /* Shrink the physically size of PostgreSQL database files */

= General =
* V13 uses [https://buildroot.org/ buildroot]
* this is an own (innovaphone) collection of packages
* For further information see: [https://buildroot.org/docs.html Buildroot Documentations]

== Requirements ==

* V13 or above
* Gateway (arm): IPx10 (with CF card) or IPx11 (with mSATA SSD)
* Gateway (arm64): IPx13 (with m2 SSD)
* Virtual (x86_64)
** HyperV with [https://docs.microsoft.com/de-de/windows-server/virtualization/hyper-v/deploy/upgrade-virtual-machine-version-in-hyper-v-on-windows-or-windows-server#supported-virtual-machine-configuration-versions VM-configuration Version] 6.2 (minimum: Windows 10 or Windows Server 2016)
** VMWare
** Proxmox/KVM/Qemu

== Default credentials ==

'''During INSTALL, the default passwords are replaced with the global Admin PW!'''
* SSH-Login with '''admin''' and '''ipapps'''
* root login with '''root''' and '''iplinux''' (the root login is not directly possible, you have to login as admin first and use the command ''su root'')
* manager App (web login) '''pwd'''

= App Platform - arm/arm64 (Gateway)=

* The installation image has a size of ~50MB. During installation, the following partitions are created<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 fat32: 200MB (contains ramdisk, rootfs and kernel)
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB

When comparing potential performance of the IPxx11 platform compared to the IPxx10 platform, there are some major differences:
* SSDs found in the xx11 are faster and more reliable than the CF found in the xx10
* the available RAM for the App Platform (as specified in column ''RAM for LAP (GB) out of RAM'' in chapter ''Technical data and recommended number of users supported'' of [[Howto:How to implement large PBXs#Technical data and recommended number of users supported|How to implement large PBXs]]) is factor 6 larger on the xx11 (1,536 GB) than on the xx10 (0,256 GB))
* the xx11 has gigabit Ethernet while the xx10 has 100Mbps Ethernet. The xx10 is therefore not well suited for Apps with larger network traffic, such as Recordings
* the CPU of the xx11 (although it runs on the same frequency) is roughly 20% faster than the xx10

While it is hard to predict the performance of the App Platform in a specific scenario, we see that in a real life environment an App Platform running on an xx11 platform can well support 150 users. The xx10 platform is estimated to support 120 users. Because CPU performance is the limiting factor, larger setups can be built based on the virtual machine platform (see [[#App services and multi-threading|App services and multi-threading]] below).

<references/>

= App Platform - x86-64 (Virtual Machine 64bit) =

* The default disk size is 16GB. It should be increased '''before''' the first start if needed!
* Multiple CPUs are supported, default is one CPU
* default RAM: 512MB
* static IP address, DNS, Gateway can be configured with the command '''setip''' on the console. Run '''setip --help''' to get a list of parameters. (Example: setip --addr=x.x.x.x --mask=x.x.x.x --gateway=x.x.x.x --dns1=x.x.x.x)
* If you have permission problems change to su user (Password is iplinux or your new admin password)
* To figure out your ip address you can use the command: ''ip address'' on the console.
* '''loadkeys de''' can be used to change to german keyboard layout (etc.)
* partitions<ref name="partition-size">Maximum partition sizes are given. The real sizes are returned by the linux 'df -h'-command. These real values will be lower, but can grow in the future with new releases.</ref>:
** /dev/sda1 ext2: 350MB (contains ramdisk, rootfs and kernel)
*** the real partition format size is smaller but there is no need to monitor sda1 as sda1 won't grow during usage of the App Platform
*** sda1 is completely exchanged during an image update and its size might have changed but will never exceed these 350MB
** /dev/sda2 ext4: depends on disk size (contains databases, log files and apps)
** /dev/sda3 ext4: 500MB (contains the rootfs)
** /dev/sda4 swap: 512MB
* VMWare Tools: Open VM Tools
* Qemu Guest Agent: installed since 110032
** The qemu guest agent can be configured in Proxmox with ''Virtio'' or ''ISA''. You '''must''' use '''ISA''', as Virtio is currently not supported.

<references/>

= Installation =
==ARM Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-armel.img'' image file.
* The installation runs without any further required step.

==ARM64 Gateway==

If you setup a Gateway with the install procedure, the App Platform is installed automatically (Https Download has to be allowed and shouldn't be blocked by any firewall.) 
You can also install it manually:
* Open App Platform -> General and '''Enable Linux Support'''. Restart the gateway.
* You need to enable Proxy-ARP on [[{{NAMESPACE}}:IP4/ETH/IP|ETH0]] or [[{{NAMESPACE}}:IP4/ETH/IP|ETH1]], so your Gateway and the Linux Appliance will share the same physical interface.
* Open App Platform -> IP and configure the IP settings of the App Platform. Restart the Gateway.
* Open App Platform -> Installation and select the given version or enter an own path to the ''app-platform-arm64.img'' image file.
* The installation runs without any further required step.

==Virtual machine==

* Import the image into your server environment.
** Proxmox: follow this description here, just with the app-platform-ova.zip: https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Proxmox_VE
* Edit the disk size, if needed.
* Start the machine and wait until it reboots and starts again.
* Note: If you need to access an IP addresses available through a VPN connection from from inside the virtual machine, it could be that you need to set the network of your VM to NAT (and also add the URL for an IP to /etc/hosts)

[https://wiki.innovaphone.com/index.php?title={{NAMESPACE}}:Concept_Innovaphone_Virtual_Appliance#Configuration More Configuration Hints regarding VM Ware]

== Backup of the Apps ==

Each App Service can have multiple instances and each instance has its own database. The manager app itself also has its own database. 
There are no other files which need to be backuped. 
The standard way to backup the databases is through the Devices App [[{{NAMESPACE}}:Concept_App_Service_Devices#Backups]]. 
 
An alternate way is to use a command file which is similar to the command files from the firmware.

===Commands===
* '''times''' 0,12 # backup only at 0 or 12 o'clock
* '''backup-instances''' http://user:pw@ip/path/#I-#D.dump PUT
** PUT and POST are supported, all instances including the manager itself are saved
* '''backup-instance''' http://user:pw@ip/path/#I-#D.dump apidemo example.com PUT
** backup a single instance with instance name and instance domain
* '''backup-manager''' http://user:pw@ip/path/#I-#D.dump

===Hash parameters===
* #L App Platform label (neu), e.g. 10024
* #A App label (neu), e.g. 130004
* #I instance name (neu), e.g. reporting1
* #D instance domain (neu), e.g. innovaphone.com
* #m MAC address of the LAP, e.g. 00ab11eeff
* #d Current date and time (plain UTC without daylight saving and timezone adjustments) 20051010-170130
* #bn rolling backup index (n >=0 and <= 9, just one digit)
* ## escapes a hash mark

= App Platform Infrastructure and Concept =
== Webserver ==
The app platform includes a webserver that is highly optimized for handling many Websocket connections at a low memory footprint.
All apps use that webserver by registering for specific HTTP subpath. So they can all use the same HTTP/HTTPS ports - typically the standard ports.

=== Import Custom SSL Certificate ===
You have to upload a PEM Certificate with the following chain structure and without password encoding.

-----BEGIN CERTIFICATE-----
(certificate: eg. your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate: eg. DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate: eg. TrustedRoot.crt)
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
(certificate Key: eg. your_domain_name.key)
-----END RSA PRIVATE KEY-----

If you have problems generating the complete and correct certificate chain, you can use tools such as https://whatsmychaincert.com/ as an aid.
'''Please keep in mind that you never give away the private part of your key.'''

=== Known issues ===
*The app platform webserver can use only the default http/https ports 80/443.
*By design, there is no possibility to restore the default webserver certificate on the App Platform, if another certificate was once uploaded. 
**If nevertheless needed, you must login with Putty (see [[#How to retrieve files from the AP| Retrieve files]]) and execute these commands as root:
**''psql -d manager -c "DELETE FROM config WHERE name='webserverCertificate'"''
**''/etc/init.d/S92manager restart''
*The app platform webserver interprets URLs case-sensitive. In other words, <nowiki>http://<addr>/file.txt</nowiki> is not the same as <nowiki>http://<addr>/FILE.TXT</nowiki>

== Database ==
The app platform creates a database for each app instance with a given password. In the installer there will be used randomly generated passwords. You can set a new database password for every instance in the Application Platform.

The apps should store all data in that database. That makes sure that a consistent backup and restore of app instances can be done by the app platform manager.
In hosted scenarios, having separate databases for each instance also makes sure that the data of different customers are clearly separated and can easily be moved from one physical platform to another.

The default configuration decline database request from extern. If you need external access you can change the PGSQL configuration (as root) in the file ''/mnt/sda2/pgsql/pg_hba.conf''.
After editing pg_hba.conf, the database-service has to be restarted with the command <code>/etc/init.d/S50postgresql restart</code>
(Please think about it before you do it, because a better way is to create your own local app with local database access.)

You can find the official documentation for the pg_hba.conf here: https://www.postgresql.org/docs/14/auth-pg-hba-conf.html

Please note that you do this on your own responsibility, that it makes sense to create a backup of the original pg_hba.conf
and that you may break your database server if you do not know exactly what you do!

Sometimes the Apps are not proper working after this. You can wait a while until everything is working again or you go the hard way:
* stop the manager
** <code>/etc/init.d/S92manager stop</code>
* restart the database-service (maybe not really necessary, but makes a good feeling)
**<code>/etc/init.d/S50postgresql restart</code>
* start the manager
** <code>/etc/init.d/S92manager start</code>

=== Nightly database analyse ===

Every database is analysed at night to keep indexes in sync with the data. This triggers a ''vacuumdb -a -z'', which updates optimizer statistics, but does '''not''' shrink the physical size of the database. 
This must be done manually in the instance settings.

== App Platform Manager ==
The App Platform Manager is the central component of the App Platform. It does the following:
* Installing app services by downloading the binaries from an app store.
* Running and monitoring app services. If an app service crashes it is restarted, automatically.
* Management of app instances and providing them with the environment they need:
** A database
** A webserver path
** A password for authentication
* Backup and restore of app instances.
* Collecting debug information like tracing and crash dumps.
* System monitoring (CPU usage, memory usage, etc).

== App Services ==
App services are runned by the App Platform Manager. They implement an interface that is used by the manager to start, stop and configure app instances. Each service runs in a separate child process of the manager.

== App Instances ==
The actual functionality of an app service is provided by app instances. They run in the same process as the app service but have a distinct webserver path and their own database. There can be 0..n instances of an app service. Instances can optionally host (web) apps that can be opened in the myApps client.

Each instance of an App service has two passwords. The instance password itself and a database password. If you want to change it you must update the password on both sides. 
The instance password must match to the password in the corresponding PBX App objects, while one instance can have different App objects. 
The database password must be just known to the manager and not outside of the App Platform.

The ''Database name'' and ''Database user'' are both limited to a length of 63 characters. By default, the App Manager would create ''<domain>''_''<instance-name>'' as value for both. This is why it is recommended to use instance names so that length(name) + length(domain) is less than 63 characters. However, if this is not possible, you can manually shorten the suggested values (both must still be unique on your App Platform).

=== Cleanup database ===
You can cleanup the instance database inside the instance settings. This starts the vacuumdb process for the instance database which frees disk space of deleted rows.
Note that this process locks the database and that sufficient disk space is needed to complete it!

=== External database host ===
You can optionally configure an external database host, if the database shall be hosted on an external host. 
Note that the App Platform Manager still creates a local database, which is then not used as long as the external host is configured.

What are external databases useful for?:
* User data is too large (files are stored as BLOB in the database)
* Other (non-innovaphone) database servers are to be used due to other regulations
* There is already an external database cluster with its own backup/restore processes which should be used
* More performance is required (please note that a local UNIX socket provides much faster results than a remote database server). Depending on the app and the task of the app, it can still be useful to use a separate server if it is faster.

==== Supported database types ====
In principle, ''PostgreSQL'' and ''MySQL'' are supported. However, please note that the respective app must be designed for the target database server type. If an app has been developed for PostgreSQL, it cannot be operated on a MySQL server.

'''Please note:''' All innovaphone apps are developed exclusively as PostgreSQL apps.

MySQL therefore only makes sense if own apps are developed and MySQL or certain MySQL features are to be used. For such apps, it is very important to deactivate the automatic Application Platform APP-Backup.
The database backup process of the App Platform uses PostgreSQL backup commands, which is why the backup would fail, so the app must be excluded from the backup, and you must take care of the backup yourself.

==== Database creation ====
If you use an external database, you have to create the database itself.
The App Platform Manager itself creates a PostgreSQL database like this (you may respect this on your database host to be compatible with the database implementation inside the Apps):
* CREATE DATABASE "dbname" ENCODING 'UTF8';
* CREATE USER "dbuser";
* ALTER USER "dbuser" WITH PASSWORD 'dbpassword';
* GRANT ALL PRIVILEGES ON DATABASE "dbname" TO "dbuser";
* ALTER DATABASE "dbname" OWNER TO "dbuser";
* REVOKE CONNECT ON DATABASE "dbname" FROM public;

==== Database connection ====
There are different possibilities to specify the host. You can use a DNS-Name, IPv4 or IPv6. A port can be optionally added with a colon.

Our PostgreSQL implementation sets sslmode=prefer, so SSL is used by default if enabled on the server.

==== Backup/Restore ====
External databases are still backuped as normal, but you can't restore such a database with the App Platform Manager on the external host! You must restore such a dump manually on your database host.

==== Database redundancy ====
In principle, it is possible to create redundancies for failure scenarios through this function.

However, there are different scenarios that need to be evaluated on a case-by-case basis:

* One database, multiple App Platforms (primary online / secondary '''offline''') where multiple apps access the same database.
** This mode of operation is legal as long as you can really ensure that only one App Platform is active at a time.

* One database, multiple App Platforms (primary online / secondary '''online''') with multiple apps accessing the same database.
** This operating mode cannot be used for innovaphone apps, as the app itself would have to be developed for such a mode, which it is not.

However, we advise great caution here! The use of the same databases from different nodes may only be used if you can ensure that the databases or runtime environments of apps cannot get into a ''split-brain'' mode.

== Relationship between app instances and app objects in the PBX ==
Typically an app instance is connected to one or more app objects in a customer PBX. This is done by configuring the same parameters on both sides:
* URL
* Password
The password is used by the PBX for authenticating itself, users and services against the app instance.

Some apps need a websocket connection with the PBX. When "websocket" is activated at the app object, the PBX establishes a websocket connection to the app instance and provides the APIs that are configured at the app object.

=== Supported scenarios ===
It is important to understand that the concept does not do any assumptions on how PBXes and APs are correlated. So you can have
* One App Platform for one customer
* One App Platform for many customers
* Many App Platforms for one customer
* Many App Platforms for many customers

Attention: The V13 installer can only configure the scenario "''One App Platform for one customer''". If you want to have a different scenario, you have to configure it manually.

For hosting or cloud scenarios you need special scenarios. Please refer our [[Howto:V13 Hosting| V13 Hosting]] instructions.

=== Restrictions ===
Currently we don't have redundancy for app instances or App Platforms.

== Update of the App Platform itself ==
The App Platform is build on top of buildroot and will receive updates and fixes from time to time. 
You can update the used build inside the Manager App by using the '''Update''' button at the top. 

It is strongly advised to make a full backup (VM) or at least backup all apps (Gateway) before you run such an update!

After the update has been downloaded and verified, your App Platform will reboot.
You can check the installation process after the reboot with the following URL: https://IP-of-AP/manager/ramdisk.log

== App services and multi-threading ==
Each App Service runs in a single process with no multi-threading, independent of the instances of the App Service. However, each instance maintains its own database connection and the database responds to this connect with the creation of a new process. Each app service therefore uses 1+''n'' threads (where ''n'' is the number of instances). All communication between app service instances and their clients must pass the single-threaded web server. On platforms with multi-threading support (i.e. VMware or Hyper-V), up to 1 + ''m'' + ''m'' * ''n'' (with ''m'' being the number of Apps and ''n'' the number of instances per App) threads can be utilized.

= AP Manager settings =

== General ==
* ''Enable Developer mode'': in developer mode, apps can be manually uploaded without an App Store
* ''Disable App security'': each App has an own unix user and if this flag is set, the user can login with SSH for debugging
* ''App Store URL'': the URL to the App Store where Apps are searched and also an update of the AP image itself
* ''Devices app URL'': the URL to the Devices App to manage the AP through Devices
* ''Devices app URL 2'': don't use!
* ''App Platform DNS name'': currently not used
* ''NTP server 1/2'': NTP servers for this AP (in addition to NTP servers retrieved by DHCP)
* ''Timezone string'': A timezone string which is used by the App Platform Manager to do certain jobs according to the configured timezone.
** Note that this doesn't change the timezone of the linux itself!
* ''DNS server 1/2'': DNS servers for this AP (in addition to DNS servers retrieved by DHCP)
* ''Database optimization time'': The database optimization process will be started at this hour (local time), with a random offset of up to 7 hours
* ''Command file'': obsolete, use the Devices App for backups!

== Security ==
* ''Current Webserver certificates'': shows the current certificates with the ability to download them.
* ''Webserver certificate'': upload a webserver certificate in PEM format
* ''AP Manager password'': the password to the web interface of the AP Manager (normally set through Devices)
* ''Linux root user'': password of the root user (normally set through Devices)
* ''Linux admin user'': password of the admin user (normally set through Devices)

== Let's Encrypt ==

Configure the certificate creation by Let's Encrypt here.

* ''Enable'': turns the automatic creation on or off
* ''Let's Encrypt App URL'': the URL of your Connector for Let's Encrypt App Service. You can copy&paste this URL from your Connector for Let's Encrypt PBX Manager Plugin
* ''Let's Encrypt App Password'': the client password of your Connector for Let's Encrypt App Service. You can copy&paste this password from your Connector for Let's Encrypt PBX Manager Plugin
* ''Key length'': 2048, 3072 or 4096 (keep in mind, that [[{{NAMESPACE}}:Certificate_management#Certificate_Key_Length_and_CPU_Usage|a higher value provides higher security but also lower performance!]])
* ''DNS Name'': the external DNS names of your device (up to 100 possible)

== Alarms and events ==
* ''URL'': URL to the Events app
* ''Username/Password'': HTTP credentials of the Events app
* ''Email address'': an email address which will get emails on full disk alarms/warnings
* ''Threshold'': All Apps will be stopped and an hourly email sent on reaching this threshold. An alarm is generated 10% before reaching this threshold and an email is sent every 24 hours.

== SMTP ==
SMTP server settings for sending emails from within the AP Manager.

== Replication ==
App Platform [[#App Platform replication|replication settings]]

== Registered Access Domains ==

== Update ==
Updates the App Platform to the latest image available on the App Store.

== Restart ==
Restarts the App Platform.

== Shutdown ==
Shuts down the App Platform.

= App Platform replication =

== Requirements ==

* 13r3 or above on both standby servers and the primary server
* at least an App Platform image starting with version 110002 (otherwise postgresql is too old)
* standby and primary servers must have the same system architecture
** arm gateways (IPx11) just with arm gateways (IPx11)
** arm64 gateways (IPx13) just with arm64 gateways (IPx13)
** x86_64 virtual machines just with x86_64 virtual machines
* the disk size on standby servers must be at least equal as the disk size on the primary server

== General ==
The configuration is done within the App Platform Manager next to the settings button under "Replication".

=== Off ===
No replication is done at all.

=== Primary ===
The App Platform acts as primary server for one or multiple standby servers. 
Max 8 standby servers can be configured. 
 
Every standby server must get a unique name on the primary server which is then also configured on the standby server itself. This is due to the fact, that the primary server preserves data for every standby server while it's not reachable. 
A standby server name must be a valid domain name, although this name is currently not used as DNS name (but might be used in the future). 
 
The password is randomly pregenerated and must be used as handed by the App Platform Manager.

==== PostgreSQL port ====
The default PostgreSQL port is 5432 and can't be changed on the primary. It must be reachable through your firewall or at least forwarded on a different port towards this App Platform on port 5432.

=== Standby ===
Configure the password from the primary and one of the not yet used standby server names. 
The host and port must be reachable through the network. You can specify a non default port which then must be forwarded somewhere else to port 5432 on your primary.

*Note: Do '''not''' configure the same standby name on different standby servers, as this will break the replication on at least one standby! 
*Note: On a standby, all '''locally installed apps are removed''' during installation

== Failure detection ==

The replication state on both primary and standby servers are continuously monitored. 
In case of a broken connection, an alarm is triggered at once and just cleared if the failure goes away. 
 
If such an alarm lasts for 5 minutes an email is send. The recipient address must be configured in the App Platform Manager settings under "Alarms and Events" and you must also provide a valid SMTP configuration.

== Failover ==

There is no automatic failover procedure. If you detect the failure state, you must get active yourself.

=== Standby down ===

Fix the standby server and see if the replication comes up again. If not, setup a new standby server which will replicate the whole database cluster from scratch.

=== Primary down ===

If the primary is down and cannot be brought into life again, you must take the following steps, depending on your configuration:

==== One standby server ====

* Disable the replication in the replication configuration. You will then have a standalone App Platform afterwards.

==== Multiple standby servers ====

* Change the replication type on one of the standby servers from standby to primary. Please note that the other standby entries must still exist here (they are automatically offered)!
* Change the host entry on the other standby servers to the new standby server. The standby server will sync the whole database cluster again, which will take time.

==== Configuration changes ====

You must also tell the PBXes and other tools to use the new primary server.

* You may simply change the IP address behind the DNS of your primary server to point to the new primary server.
**Note: to ensure rapid recognition of the new DNS target, the definition of an appropriate TTL value is recommended
* Without DNS, you must currently modify the configuration by replacing the IP address of the old primary with the new address.
** This must be done in every master PBX configuration.
** This must be done in every App configuration which may use this IP address, e.g. Devices which rolls out an alarm server configuration

== App Platfom update ==

If you're running an active standby server and the major version of the PostgreSQL database didn't change, you can simply update primary and standby servers independently. 
 
If it contains a ''new major version'' of the PostgreSQL database, you must follow these steps:

* deactivate replication on all standby servers (which promotes these standby servers to active servers)
* ensure that the '''same''' App Platform Manager version is running on primary and standby servers!
* perform the App Platform update on the primary server
* perform the App Platform update on the standby servers
* reactivate replication on the standby servers (which will do a full replication again, so it might take some time)

Alternativly you may setup the standby server from scratch directly with the new App Platform image version.

Sadly there is currently no better method offered by PostgreSQL to perform such an upgrade.

See also https://wiki.innovaphone.com/index.php?title=Howto14r2:Firmware_Upgrade_V14r1_V14r2#App_Platform_and_Apps

== Technical backgrounds ==

=== Streaming replication ===

We use the asynchronous [https://www.postgresql.org/docs/9.3/warm-standby.html#STREAMING-REPLICATION streaming replication of PostgreSQL]. A transaction thus just waits for a commit on the primary server. Standby servers will receive the transaction asynchronously afterwards to avoid a reduced writing performance. 
A primary server keeps the neccessary WAL files for every standby server until the standby fetched the neccessary information. 
This fact can lead to higher disk space usage on the primary if one or multiple standby servers are offline for a while.

Take care to fix broken replications as soon as possible to avoid a full disk on the primary server!

=== What is replicated ===
The whole database cluster of an app platform is replicated. This includes every database of every instance and the database of the App Platform Manager itself. 

=== App Services on standbys ===
The database of the App Platform Manager itself also contains the App service binaries to be able to restore applications in a failover case. 
You do not have to install App services on the standby if you install them on the primary. 
App Platform Manager and Webserver can be updated as usual through the App Store or the Devices App if the standby is connected to Devices.

=== App Platform Manager configuration of the standby server ===
The App Platform Manager configuration of the standby server cannot be stored inside the database, as the database is readonly. So it is stored inside a configuration JSON file under ''/home/root/standby.conf''. 
This configuration is backed up as usual by a Devices backup job and can be also manually restored on a standby (not on a primary though!).

Configuration options from the primary are not synced to the standby server, as the standby server has its own configuration (as it could be in a different network etc.)!

=== No automatic failover ===

There is currently no automatic failover mechanism. PostgreSQL doesn't offer multi master replication, so writing is just possible on the primary itself. Standby servers have a readonly database. 
Let's consider the following use case if we would implement an automatic failover with the current technical possibilities: 
* The primary server is connected to a master PBX.
* A slave PBX is also connected to the primary server in another location.
* A standby server is in this location and replicates from the primary.
* The internet connection between primary and standby fails.
* The standby promotes itself to primary, so that the master PBX now writes to the old primary and the slave PBX now writes to the "new" primary.
* The internet connection comes up again and both primary and standby servers now have databases which are out of sync and which cannot be merged.

=== Security ===

* port 5432 must be reachable on the App Platform
* For every standby a PostgreSQL user is created with the REPLICATION role on the primary. Just this user has access to the database server from non localhost connections.
* You cannot establish a standard connection with such a user and modify/read from tables.
* The replication connection is established over TLS by default.

= App Installer PBX Manager Plugin =
== Requirements ==

* V14 and above

== General ==

The app installer plugin allows IT administrator (with access to the PBX Manager) to install/update/delete new apps from the innovaphone app store including Partners apps. It is automatically available with existing app platforms or after adding a new one in the PBX Manager.
It offers a view to the App Platform Manager‘s App Store with all the available functionalities and simplifies the install, update and uninstall of apps.

== Dedicated AP for each user ==

Installing a new app will install the app service and add a new instance with the user’s domain. The instance is automatically started. 
This further enables the configuration of the instance through its respective PBX Manager plugin. 
Uninstalling the app will remove the app service and the corresponding instance.

== Shared AP between users ==

Installing a new app works in a similar way to that of the dedicated AP. However, each time a new user installs the app, only a new instance is created if the app service is already installed. 
A user can uninstall the app, in this case the corresponding instance is deleted. If no more instances exist, then the app service is uninstalled. 
The administrator can only update the app service in such scenario.

= Known Issues =

== Reboot after an image update hangs (ARM gateway) ==

If it happens, that the App Platform doesn't recover after the reboot, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
If '''Kernel command line''' is set to '''/dev/ram0''', the App Platform booted the ramdisk. 
 
Try to fetch the upgrade log file:
https://[APP-PLATFROM-IP/DNS]/manager/ramdisk.log
 
If this doesn't work, try to login with putty in this case (default credentials admin/ipapps and root/iplinux) and issue this command: 
''cat /apps/install_step1.log'' 
 
If this file contains '''finished''' at the end, you can reconfigure the settings under App Platform -> General: 
* press '''Stop'''
* Initrd file: empty
* Kernel command line: '''root=/dev/sda3'''
* Ramdisk size: empty
* press '''Start'''

The App Platform should boot and run the already updated image.

<pre style="color: red; font-size:150%;">---WARNING---
If the file doesn't contain "finished" at the end, you may still need to wait, as an upgrade may take some time!
Do not reconfigure without being sure that the upgrade has finished, otherwise your system may won't run!</pre>

== Reboot after an image update boots always into rescue mode (virtual machine) ==

This most likely means that the image installation didn't finish the first time and was interrupted before the bootloader settings could be changed back to the default partition. 
 
If your App Platform doesn't boot or isn't normally accessible after manual selection of the standard entry in the boot menu, you need to '''revert''' to a '''snapshot/backup''' prior to the update. 
If your App Platform runs normally though, you can follow this instruction to change the default boot entry: 
 
* boot into the '''rescue''' partition
* login with root/iplinux
* edit the file /boot/grub/grub.cfg
** search the line with '''set default=0''' and change it to '''set default=1'''
** reboot

== App Platform doesn't start after an update ==

=== Gateway ===
If it happens, that the App Platform doesn't want to start an update, please open the Admin UI of the corresponding gateway and take a look at App Platform -> General. 
* '''Shutdown''' the App Platform and '''Stop''' it 
* Set '''Kernel command line''' to '''/dev/ram0''' 
* Set '''Initrd file''' to '''ramdisk.ext2.xz''' 
* Set '''Ramdisk size''' to '''100000''' 
* '''Start''' the App Platform now. 

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

Note: This process can take a while, after it's finished it reboots and automatically change the '''Kernel command line''' value.

=== Virtual Machine ===

Boot into the '''rescue''' partition.

The App Platform now either applies the image update or it reboots into the old image. Try the image update afterwards again.

=== It still doesn't start ===

If it still doesn't start, configure the App Platform to boot from /dev/sda3 (or inside a VM start the second boot loader entry) and login with SSH as root.
Then do a first check to verify that you have a specific error due to an incomplete update or a wrong update order:

* /etc/init.d/S92manager stop
* /apps/manager/manager
* if this outputs '''error while loading shared libraries: libcrypto.so.3:''' you have a manager version which cannot run on the current image.

In this case you must download an older build (14r1 1410593):

* /etc/init.d/S92manager stop
* wget --no-check-certificate -O /apps/manager/manager https://webbuild.innovaphone.com/1410593/arm/manager/manager
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* wget --no-check-certificate -O /apps/webserver/webserver https://webbuild.innovaphone.com/1410593/arm/webserver/webserver
** inside a virtual machine, use '''x86_64''' inside the path instead of '''arm'''
** on an IP6013, use '''arm64''' inside the path instead of '''arm'''
* chown root:root /apps/manager/manager
* chown root:root /apps/webserver/webserver
* chmod +x /apps/manager/manager
* chmod +x /apps/webserver/webserver
* echo 110000 > /mnt/sda1/label
** this allows the manager to perform an image update again
* /etc/init.d/S92manager start
* now perform an image update and '''afterwards''' update your apps again

== Webserver doesn't respond after an image update ==

If you can't reach the web UI after an image update, please try to connect with SSH as admin user and delete old coredumps, which may prevent the App Platform Manager from starting correctly:
* su root (become root)
* rm -f /mnt/sda2/log/core_dumps/*/*
* /etc/init.d/S92manager restart

Check if you can now reach the App Platform again.

= Tracing =
Each App Service has its own log file, which can be accessed through the Manager App. You can configure a log file size for each App Service. 
Each App Intance has its own trace flags. The following trace flags can be set: 

* Alarm client: used by the manager to send alarms to an alarm server
* App: logs from the App Service itself
* App WebSocket: logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
* AppSharing: just native clients
* AppProxy: just native clients, logs requests which are proxied between the local webserver and the remote server
* Audio: just native clients
* Browser: just native clients
* Command: the command interface is used to execute shell commands, e.g. used by the manager App
* Config: logs config changes of an App
* Database: database logs
* DB files: database file logs
* DNS: DNS request logging
* DTLS: just native clients, DTLS request logging
* Ethernet: interface to get ethernet adapater infos, just manager App
* File: logs for file system access (synchronous), e.g. manager App
* Files: logs for file system access (asynchronous)
* HTTP client: http client logs
* HTTP file: logs for static HTTP files
* ICE: just native clients
* LDS: local domain sockets
* Media: just native clients
* Media channel: just native clients
* Process: IProcess interface logs which is used for spawning, killing processes etc.
* SMTP: SMTP client logs
* TCP: TCP logs
* Time: ITime interface logs
* TLS: TLS logs
* TURN: just native clients
* UDP: UDP logs
* Video: just native clients
* WebSocket client: logs outgoing websocket connections
* Webserver traffic: logs incoming HTTP traffic, which is forwarded from the webserver to the App
* WebDAV service: logs WebDAV requests to the App
* Webserver: enables webserver specific logs

== RPCAP ==

If you open the Manager App, click on the Manager in the left list and then on the Diagnostics button, you can enable RPCAP. 
You can add the interface in wireshark with the string:
rpcap://<APP-Platform-IP>/eth0

'''Please don't forget to disable RPCAP after your testing!'''

= How-Tos =

== How to retrieve files from the App Platform ==
To retrieve files from the App Platform which can not be retrieved via the App Platform manager UI, you can connect to the App Platform using the SCP protocol on port 22. 
 
First copy files to /home/admin as root with Putty or another SSH client:
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''su root'' to be root (''iplinux'' as default password)
 
You can now copy files to ''/home/admin'' (e.g. from /var/log/apps/manager/...). 
 
You can create a tar archive with all logs like this:
* cd /home/admin
* tar -cf - /var/log/* | xz -z - > log.tar.xz
** you may want to exclude coredumps (due to their size):
** tar -cf - --exclude=/var/log/core_dumps/* /var/log/* | xz -z - > log.tar.xz
* chown admin:admin /home/admin/log.tar.xz
 
Then copy the files to your local system, e.g. with WinSCP 
* use ''SCP'' as protocol (NB: WebDAV is not supported on most of the directories on the App Platform )
* use the ''DNS'' name or IP address of your App Platform (not the PBX)
* use user ''admin'' and the appropriate password (''ipapps'' by default)
* use ''/home/admin'' as start directory
* copy the needed files

== App Platform disk space warning ==

If the configured threshold is reached, all Apps are stopped inside the App Platform . You must then free disk space somehow.

=== Find large instances ===
Click through your apps in the tree on the left side and take a look at the database size of each instance.

=== Delete data inside an instance ===
It depends on the type of app if you can delete data or not. E.g. you can start the Files app and delete files inside this app. 
This won't reclaim disk space though due to the way how PostgreSQL databases work, so you need to follow this guide to reclaim the disk space:

* start the corresponding App
* delete data inside the App
* optimize disk usage of the database by cliking on the button "Clean up database" under Edit instance. If this does not help, continue with the following steps.
* stop the corresponding App again
* download a backup of the instance (backup button at the top), this backup contains the whole instance data, also the password of the instance
* delete this specific instance
* restore the downloaded backup (restore button at the top)

Depending on the hardware and the size of the instance, this process may take hours to complete!

=== Resize the disk ===
The resizing of a disk is just possible for virtual machines, see [[#Resizing the disk of a Virtual machine|Resizing the disk of a Virtual machine]].

=== Delete the whole instance ===
If there is no other possibility, you can delete the whole instance. Afterwards you recreate the instance with the same values and a new random password. Don't forget to set this password in the corresponding PBX App objects though!

=== Restart the Apps or the App Platform ===
If you have enough disk space again, you must either restart the whole App Platform or you manually start all Apps again.

== App Platform/Apps app not online anymore due to full disk ==
If the apps app is not online anymore and you can't access any apps anymore, try to login with an SSH client to see if your disk is full.
Login as admin and afterwards as root (su root). 
 
* issue '''df -h''' and see the disk usage of /dev/sda2, if this is 100%, your disk is too full
* stop the manager
** /etc/init.d/S92manager stop
* empty the 500 MB file, which is exactly for this case here (manager must be 13r1 SR9 or higher to have this file)
** echo "" > /mnt/sda2/empty_if_no_space
* delete log files to recover some space
** rm /var/log/apps/*/*
** rm /var/log/core_dumps/*/*
* restart the postgresql server (see the output if this worked or not)
** /etc/init.d/S50postgresql restart
* restart the manager
** /etc/init.d/S92manager restart
* wait until everything is online again
* open the Apps app and try to find the instance which uses the most disk space and try to delete files/content from it
** you may want to stop all app services first to prevent more writes to the database
** if not possible, you can delete this instance, but you'll loose all data from this instance then!
* after that you can try [[{{NAMESPACE}}:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files|Reference14r2:Concept_App_Platform#Shrink_the_physically_size_of_PostgreSQL_database_files]] to free up space
** If this does not work you can create a backup from the database, delete the database and import the database again.
* free up at least 500 MB so that the manager can create the file again
* delete /mnt/sda2/empty_if_no_space if you are done and restart the manager:
** rm /mnt/sda2/empty_if_no_space
** /etc/init.d/S92manager restart
** the manager restart automatically recreates the empty_if_no_space file if this file doesn't exist

Make sure, that you do '''not''' have backups configured to a local files instance while this files instance is not excluded from backups.
An instance can be excluded from backups in the instance settings in the App Platform Manager.

If all of this doesn't help, you can resize the file system on a VM:
* proceed with [[{{NAMESPACE}}:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine|Reference14r2:Concept_App_Platform#Resizing_the_disk_of_a_Virtual_machine]]

== Resizing the disk of a Virtual machine ==

Do '''NOT''' resize if you're running an App Platform version higher than '''110000''' and lower than '''110027''' or your data will be lost!
Please update your App Platform to version 110027 or higher before you start resizing your disk.

* stop the VM
* expand the disk using your VM utilities
* start the VM and boot from the first boot entry '''rescue/setup'''
* login with '''root''' and '''iplinux'''
* execute this command: '''/home/root/install_step1.sh log.txt resize'''
* the VM reboots automatically after a successful resize

== Shrink the physically size of PostgreSQL database files ==
Tuples that are deleted in your database are not physically removed from the database-file. So the claimed space on the harddisk is still in use after the delete operation.
If you need to free up some disk space you can force to reorganize the physically database-file on your harddisk.

You can also start this process through the instance settings as long as the App Platform Manager is still running.

'''Important: You are operating on the Database, you have to make a Backup of your Database before you do this!'''

Login via SSH to the APPlatform with the ''admin'' User
su root

=== All databases ===
/etc/init.d/S92manager stop # not always needed, but in case of database errors recommended, of course no app is online then
sudo -u postgres reindexdb -a
sudo -u postgres vacuumdb -a -f
/etc/init.d/S92manager restart # just execute if the manager has been stopped above

=== single database ===
sudo -u postgres reindexdb -d dbname # for a single database with dbname
sudo -u postgres vacuumdb -d dbname -f # for a single database with dbname

Note: This may take some time and the App database is not available during this time

After the process you can check the free dispace via <code>df -h</code>. You can check the claimed space from the database file with the command <code>du -sh /mnt/sda2/pgsql/</code>.

== Change IP Addresses / DNS Names / System Name ==

If you want to change the System Name or the DNS Name of the PBX and/or App Platform Platform you must change records manually '''in the described order'''!
You have to know the Admin password to directly Login to the App Platform .

=== App Platform ===
; Settings - General
* ''Devices app URL''
* ''App platform DNS name''

; Settings - Alarms and Events
* ''URL''

; All Instances
* ''Domain''
* ''Webserver path''

=== PBX ===
Download the configuration and ''search/replace'' in the config file. Upload the config file and reboot.

Manual:
* ''URL'' in all PBX Object (Apps, Voicemail ...)
* [[{{NAMESPACE}}:Gateway/CDR|CDRx]]
* [[{{NAMESPACE}}:PBX/Config/General|IP address for App Platform]]
* [[{{NAMESPACE}}:PBX/Config/myApps|Reset Password Page]]
* [[{{NAMESPACE}}:PBX/Config/Authentication|Verification link]]

Depending on your change you have to activate/deactivate the Setting [[{{NAMESPACE}}:PBX/Config/General|Operation without DNS]]

=== Additional Devices / Steps ===
* ''Devices Registration URL''
** There is no automatism to change the URL on all devices in your setup.
** If you have the option to use DHCP, you can temporarily overwrite the [[{{NAMESPACE}}:Services/Update|Update URL]] and execute a [[{{NAMESPACE}}:Concept_Update_Server|custom update script]] to change the ''Device Registration URL''
* ''Alarm server''
* Reverse Proxy configuration
* Change ''Domain Name'' in Devices if you have also changed the system name

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

initial error at 1500329378: ext4_journal_start_sb:328
last error at 1500329378: ext4_journal_start_sb:328

Or you get events like "Broken file system" from your App Platform .

This indicates a file system failure on the Linux Installation.

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

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

=== Gateway ===

* Open the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the Kernel command line from root=/dev/sda3 to root=/dev/ram0
** modify the Initrd file to ramdisk.ext2.xz
** modify the ramdisk size to 100000
** start Linux again
:: This will run Linux on another (hopefully sane) partition.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system

* go back to the WebGUI of the gateway running your LAP and proceed to ''App Platform/General''
** terminate Linux (''Status/Stop'')
** modify the ''Kernel command line'' from ''root=/dev/ram0'' to <code>root=/dev/sda3</code>
** clear the Initrd file field
** clear the ramdisk size field
** start Linux again
:: This will run Linux on the original partition.

=== VM ===

Restart the VM and select the first entry in the boot menu from grub.

* use [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html putty] to log in to the LAP's command line ( try either user: root, pw: iplinux '''OR''' user: admin, pw: ipapps)
** use this to be root <code>su - root</code> (password iplinux)
** on the command prompt, use <code>e2fsck -p -f /dev/sda2</code>
** on the command prompt, use <code>e2fsck -p -f /dev/sda3</code>
:: this should fix any issue on the file system
* Reboot your VM
[[Category:Concept]]

== How to create a memory dump of a running process ==

Sometimes it's usefull to have a memory dump of a running process to investigate certain issues.

* login with SSH and become root
* find out the PID of the relevant process, e.g. with ''ps aux | grep /apps/manager/manager | grep -v grep''
* gdb --pid PID -ex gcore --batch
* this creates a core file core.PID
* download this core file with WinSCP or similar tools

== Move instance database to external database host ==

In case you want to use an external database server instead of the integrated:

* download a backup of the specific instance over the App Platform Manager
* create a postgresql database on the external host:
** createdb --encoding=UTF-8 exampledb
* restore the backup
** pg_restore -d exampledb backup-exampledb.dump
* change the ownership to a specific postgresql user (which you have to create yourself first)
** psql -d postgres -c "ALTER DATABASE exampledb OWNER TO exampleuser"
* configure the database host, name, user and password on the instance inside the App Platform Manager