Linphone remote provisioning

Introduction

Linphone Android, iOS and desktop versions support remote provisioning via HTTP. This consists in downloading a Linphone configuration file (linphonerc) in XML format from a HTTP server URI. The values defined in the configuration file are applied to the configuration of Linphone.

This can be used to enable/disable some codecs, configure the SIP transports (SIP/TLS, SIP/TCP, SIP/UDP), enable/disable video, configure DSCP bits, and much more.

Despite the internal representation of Linphone INI-style configuration, the choice of using XML for remote provisioning was made because it is more likely to be used by web applications for the case where the configuration would be dynamically created.

Usage

You can provide a provisioning URL in the settings of Linphone for supported platforms so that user can enter or modify the URL where configuration is loaded. 

The configuration will be downloaded and applied at the next start of the application (for Android, it is before the initialization of the Linphone core).

The default value for the URL can be set in the initial linphonerc configuration file included in the packages, in which case the configuration is fetched and loaded immediately at first start.

You can also directly fill the URL in the account wizard, in which case the application will automatically restart itself and download the configuration.

Linphonerc configuration file

A typical linphonerc configuration file looks like this:

[net]
download_bw=2048
upload_bw=1024
firewall_policy=ice
stun_server=stun.linphone.org

[sip]
sip_tcp_port=5070
ping_with_options=0
media_encryption=none
dscp=0x0

[video_codec_0]
mime=VP8
rate=90000
enabled=1

[video_codec_1]
mime=H264
rate=90000
enabled=1
recv_fmtp=profile-level-id=428014

There are actually many configuration items that can modify default behaviours of the Linphone engine.

The keys understood by liblinphone in a linphonerc configuration file are not officially documented.
We invite developers to refer to our usage examples in apps, for example linphone-iphone/Resources/*.rc files.

Additionally, it is possible to configure a Linphone application manually and then examine the content of the linphonerc file generated by the app, in order to store the configuration.

Linphone has its own default configuration built-in in the sources: it does not need any configuration file to accept to start. These files are located as follow:

  • on iOS:
    • Resources/linphonerc: default configuration for iPhone devices. Applied at first launch only.
    • Resources/linphonercipad: same for iPad devices.
    • Resources/linphonerc-factory: forced configuration for iPhone devices, applied at each launch. Any change to this set of options will be lost on next launch.
    • Resources/linphonerc-factoryipad: same for iPad devices.
  • on Android:
    • res/raw/linphonerc_default: default configuration for phone devices. Applied at first launch only.
    • res/raw-sw600dp/linphonerc_default: same for tablets devices.
    • res/raw/linphonerc_factory: forced configuration for phone devices, applied at each launch. Any change to this set of options will be lost on next launch.
    • res/raw-sw600dp/linphonerc_factory: same for tablets devices.

As a result, it is recommended to put in the provisioning configuration file only items for which a change is required compared to the default behavior.

XML formatted configuration file

An XML converted configuration file looks like this:

<config xmlns="http://www.linphone.org/xsds/lpconfig.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.linphone.org/xsds/lpconfig.xsd lpconfig.xsd">

<section name="sip">
   <entry name="sip_tcp_port">5070</entry>
   <entry name="dscp">0x0</entry>
   <entry name="ping_with_options">0</entry>
</section>
<section name="video_codec_0">
   <entry name="mime">H264</entry>
   <entry name="rate">90000</entry>
   <entry name="enabled">1</entry>
</section>

If you want to apply your changes only once (eg. not at each start, you have to enable the transient_provisioning parameter):

<section name="misc">
<entry name="transient_provisioning">1</entry>
</section>

The mapping between INI and XML representation is quite obvious.
A tool is integrated into the Linphone desktop version in order to convert from INI-style to XML.
Here’s typical usage of:

./tools/lpc2xml_test convert /.linphonerc /tmp/linphonerc.xml

Notes: By default, lpc2xml will produce an XML that will not overwrite existing keys.
If you want to overwrite the existing configuration, you must append the overwrite="true" attribute for each key that you want to override, i.e.:

[...]
<entry name="sip_tcp_port" overwrite="true">5070</entry>
[...]

Sample provisioning file

Here's a sample provisioning file:

https://www.linphone.org/remote_provisioning.xml

Be careful, it is configured to overwrite the first proxy config and auth info you might have!

Also the account it will configure is a "public" one, you may receive calls or messages from unknown people.

QR code provisioning

Mobile version also supports downloading remote configuration from a QR code (if the content of the QR code contains an URL to a valid provisioning xml file of course).

Here's a QR code that redirects to the above provisioning file:

remote_prov.png

Created by SandrineAvakian on 2017/02/10 10:16