Intro

Provisioning is the feature that allows network and provider administrators to remotely configure Jitsi instances that they are responsible for.

Jitsis provisioning module uses http. This means that, based on a few parameters like an IP or a mac layer address, or a user name and a password, a simple script on a web server or an advanced provisioning system like JitsiProvS can feed to a freshly installed Jitsi all the details that it needs in order to start making calls, downloading updates or configure codec preferences.

Of course, in order for this to work, Jitsi would first need to find out where the provisioning web server is. This can happen either automatically, using discovery protocols like DHCP or mDNS (a.k.a. Bonjour), or by manually entering a provisioning URI in Jitsis configuration form.

The easiest way to have Jitsi connect to a provisioning server is to configure the provisioning URL in its configuration form. Jitsi also supports automatic provisioning discovery via DHCP and Bonjour both of which are discussed later in this document. To do so, go to options => advanced => provisioning and check Enable provisioning (if not already checked), then select Manually specify provisioning URI and enter a URI.

A provisioning URI is an HTTP or HTTPS URL optionally followed by several parameters. The URI would most often point to a provisioning server-side script (e.g. PHP, CGI, servlet, ). Please note that we strongly recommend you only use HTTPS unless you have very good reasons not to. Provisioning POST requests generally contain sensitive information like passwords and you definitely dont want that being sent in clear text.

Here is an example of a provisioning URI:

Note that in the above URI the names of the parameters to the left of an equal (=) sign only depend on you and the web script that you are using in your provisioning environment. Those to the right however are parameters supported by Jitsi and they always come surrounded by accolades and prefixed with a dollar sign (e.g. ${param_value} )

Currently, Jitsi supports the following parameters:

See Configure Jitsi With Provisioning for a list of parameters that allow for hiding various menu entries from the UI.

A provisioning script is something that you write and run on your web server. It handles incoming provisioning requests and it serves configuration properties to Jitsi according to the parameters that these requests contain.

A provisioning script MUST always return content formatted as a valid properties file. Thats pretty much the only limitation and other than that, you can have almost anything in it. You can certainly use the output to configure absolutely any aspect of Jitsi.

Quite often, a provisioning script would use the parameters from the provisioning URI to determine the exact properties that it is going to return. A common example is the provisioning of a SIP account that often depends on either the hardware address or the user name and password entered by the user.

In order to retrieve its configuration properties from the provisioning script, Jitsi would use an HTTP POST request. All the parameters that are present in the provisioning URL (e.g. username, password, osname, ) would then be encoded as parameters of that POST request. This is important to note and may be a bit confusing since the request makes it look as if we would be doing a GET.

JitsiProvS is one example of a Jitsi provisioning server written in python. You can use it as is or extend it to fit your needs. You are of course also free to create your own versions.

Following is a simple PHP provisioning file:

You can use the special property value ${null} when youd like to remove (unset) all properties beginning with the specified prefix. Note that properties are processed in the order that the provisioning script returns them. It is therefore possible to use ${null} in the beginning of a provisioning file, have it remove a group of properties like a SIP account for example, and then feed a new SIP account in the same provisioning file.

The property provisioning.ALLOW_PREFIX tells Jitsi that through the rest of the provisioning file, it should ignore any properties that do not match the specified prefixes. The value of the property would hence contain a number of strings separated by the | (pipe) character.

The provisioning.ENFORCE_PREFIX is somewhat similar to ALLOW_PREFIX. Jitsi would use this property to make sure that your Jitsis configuration file only contains properties matching the specified prefixes and it would remove all those that dont, regardless of whether they were provisioned through a provisioning script or were set by the user.

Important note: Your provisioning script should indicate authentication problems (e.g. wrong password) using a 401 HTTP error response. After receiving such a response, Jitsi would prompt the user to enter the credentials again.

DHCP is one way for Jitsi to discover a provisioning URI without user interaction. To make Jitsi use DHCP provisioning, go to options => advanced => provisioning, check Enable provisioning and then select the DHCP radio button.

In order to get the provisioning URL via DHCP, somewhere on the network a DHCP server has to be running on port 6767. This means that if you already have a DHCP server in your network, you would probably need to install a second one (although this one would be extremely simple to configure so dont worry 🙂 ).

We expect to find our provisioning URI in option 224 so thats where your server needs to serve it.

Following is a sample dhcpd.conf file that you can use almost as is in your own network. Youd probably only need to adjust the subnet and the URI itself:

Note: the provisioning DHCP server does not need to provide IP addresses to machines. All it does is return the provisioning URI to whoever asks.

To configure provisioning via Bonjour, go to options => advanced => provisioning, check Enable provisioning, and then select Bonjour.

In order to get the provisioning URI via Bonjour, you would need to make sure that an mDNS server is running somewhere on your network and that it is configured to advertise the provisioning URI.

Avahi is one of the most popular mDNS servers. Heres what you need to do in order to make it provision Jitsi

On Unix/Linux:

Note that name MUST not be changed since Jitsi will look for the service name Provisioning URL. The host-name is not a FQDN and has to be suffixed by .local, next step will tell avahi about the IP address of this host name. The URL parameters is added in this way paramname=$paramname.

match the one in parameter of provisioning.service file.

would become something like

More:

Provisioning | Jitsi