If you are looking for Jitsi Meet, the WebRTC compatible video conferencing product click here.

Intro

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

Jitsi’s 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 Jitsi’s configuration form.

Jitsi's Configuration Form
Jitsi’s Configuration Form

Provisioning URI and parameters

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 don’t want that being sent in clear text.

Here is an example of a provisioning URI: 

https://example.com/provisioning.php?user=${username}&password=${password}
      &os=${osname}&hw=${hwaddr}&uuid=${uuid}&hostname=${hostname}

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:

  • username: The name of a user account that you may use to determine the kind of information that you’d like to feed to Jitsi. If you use that parameter, Jitsi would prompt the user to manually enter a user name so obviously they need to know what they are being asked for.
  • password: A password string that you can use when authenticating the above user name. If you use that parameter, Jitsi would prompt the user to fill in a password field.
  • osname: the operating system that Jitsi is currently running on.
  • ipaddr: The IPv4 or IPv6 address that Jitsi is using to communicate with you (could be helpful if, for some reason you are not receiving the message directly from Jitsi or in case you don’t have access to the source address of the incoming messages).
  • hwaddr: The hardware address of the device that Jitsi is using to communicate with you
  • build: Jitsi’s current build number
  • uuid: The UUID of the device running Jitsi
  • arch: The architecture of the device running Jitsi
  • hostname: The host name of the machine running Jitsi.
  • home.location: the location of Jitsi’s configuration directory on the host machine
  • home.name - the name of Jitsi’s configuration directory
  • system.<property_name>: Any Java System property where <property_name> is the name of that property. For example ${system.user.name} would be replaced with the value of the “user.name” property: the user name that Jitsi is executed with.
  • env.<var_name>: Any environment variable where <var_name> is the name of that variabl. For example ${env.PATH} would be replaced with the value of the “PATH” environment variable.

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

A sample provisioning script

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. That’s 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: 

<?php
// remove all properties recursively for this property name
echo "net.java.sip.communicator.impl.gui.main.MainFrame=\${null}\n";

// ensure that the next properties will have the right prefix otherwise 
// they will not be added to configuration
echo "provisioning.ALLOW_PREFIX=net.java|org.ice4j|java.net\n";

// properties for a specific OS (here Linux)
if($_POST['osname'] == "Linux")
{
  echo "net.java.sip.communicator.impl.gui.main.MainFrame.height=250\n";
}
else
{
  echo "net.java.sip.communicator.impl.gui.main.MainFrame.height=750\n";
}

echo "net.java.sip.communicator.impl.gui.main.MainFrame.width=520\n";
echo "net.java.sip.communicator.impl.gui.main.MainFrame.x=800\n";
echo "net.java.sip.communicator.impl.gui.main.MainFrame.y=20\n";

// check that all properties of the configuration respect the following prefixes
echo "provisioning.ENFORCE_PREFIX=net.java|org.ice4j|java.net\n";
?>

You can use the special property value “${null}” when you’d 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 Jitsi’s configuration file only contains properties matching the specified prefixes and it would remove all those that don’t, 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.

Provisioning with a DHCP server

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 don’t worry :) ).

We expect to find our provisioning URI in option 224 so that’s 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. You’d probably only need to adjust the subnet and the URI itself: 

# provisioning option definition
option sc-pserv code 224 = text;
# some characters like '~' must be encoded, 
# see http://www.blooberry.com/indexdot/html/topics/urlencoding.htm
option sc-pserv "https://provisioning.domain.org/provisioning.php?username=${username}&password=${password}&ipaddr=${ipaddr}&hwaddr=${hwaddr}&osname=${osname}&build=${build}&arch=${arch}";

subnet 192.168.0.0 netmask 255.255.255.0 {
  authoritative;
}

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.

Bonjour provisioning

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. Here’s what you need to do in order to make it provision Jitsi

On Unix/Linux:

  • Install avahi-daemon if not already installed.
  • Create a file in /etc/avahi/services/provisioning.service 
<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
  <name>Provisioning URL</name>
  <service protocol="any">
    <host-name>provisioning.local</host-name>
    <type>_https._tcp</type>
    <port>443</port>
    <txt-record>path=https://www.example.org/provisioning.php</txt-record>
    <txt-record>username=${username}</txt-record>
    <txt-record>password=${password}</txt-record>
    <txt-record>osname=${osname}</txt-record>
    <txt-record>build=${build}</txt-record>
    <txt-record>ipaddr=${ipaddr}</txt-record>
    <txt-record>hwaddr=${hwaddr}</txt-record>
    <txt-record>uuid=${uuid}</txt-record>
    <txt-record>arch=${arch}</txt-record>
  </service>
</service-group>

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 <txt-record>paramname=$paramname</txt-record>.

  • Add in /etc/avahi/hosts file the IP address of the provisioning server. The server name must

match the one in <host-name> parameter of provisioning.service file. 

# enter the IP address of the provisioning server
192.168.0.254 provisioning.local
  • Restart avahi

Miscellaneous

  • Support for password encryption. Account passwords that come from the provisioning server would need to be in clear text (all the more reason to use HTTPS). They would then be encrypted by the provisioning module since the server doesn’t know what encryption key the client is using. Note however that clear text passwords need to be provisioned via the PASSWORD account property. Then would then be stored in the corresponding ENCRYPTED_PASSWORD property. For example 
 net.java.sip.communicator.impl.protocol.jabber.acc12911123.PASSWORD=mypassword

would become something like 

 net.java.sip.communicator.impl.protocol.jabber.acc12911123.ENCRYPTED_PASSWORD=x5ElABCKLjzDm
  • Account property identifiers MUST always start with the “acc” substring. It doesn’t matter what you put after the “acc” as long as it’s unique between the accounts and the same across the different properties for the same account. But, again, you do need to start with “acc”.