Installing XDS


Before installing, make sure you understand the XDS Architecture and links between components.

The XDS architecture has the following components:

  • XiVO
  • Media Server (MDS) (one or more)

An XDS needs also:

  • a Reporting Server for the centralized call history,
  • a CTI Server for the UC features.

This page will guide you through:

  1. the configuration of the XiVO (see XiVO Configuration section)
  2. the installation and configuration of the MDS (see Media Server Configuration section)
  3. and the configuration of the CC (Reporting and CTI Server) (see XiVO CC Configuration section)


Before starting you need to have 3 servers. Here’s a table summarizing what we are installing. Replace the IP by those you chose.

Server server1 server2 server3
Role XiVO Media Server Reporting/CTI Server
Name mds0 mds1 cc
IP Data

XiVO Configuration

On server1:

AMI configuration


Once a media server is defined in webi, Reporting Server will use the VoIP interface for AMI connection to all media servers and XiVO. Here we authorize it on XIVO.

If XiVO CC is installed, do the following steps before adding media server. Otherwise you can first define media servers and do these steps right after XiVO CC installation, but before starting it to prevent problems with fail2ban.

  1. Edit existing file /etc/asterisk/manager.d/02-xivocc.conf to add permission for Reporting Server:

    • permit to authorize the VoIP IP of the Reporting Server. E.g.:

  2. Apply the configuration:

    asterisk -rx 'manager reload'

Define Media Servers


Here we define our Media Servers (MDS) names and VoIP IP address.

In XiVO webi,

  1. Go to Configuration -> Management -> Media Servers
  2. Add a line per Media Server (MDS) (below an example for mds1):
    1. Name: mdsX (e.g. mds1)
    2. Displayed Name: Media Server X (e.g. Media Server 1)
    3. IP VoIP: <VoIP IP of mdsX> (e.g. - note: the VoIP streams between XiVO and mdsX will go through this IP

Once you define a media server, you will be able to create local SIP trunks that exist only there. The location can be set in tab General ‣ Media server in the SIP trunk configuration.

Define Media Servers for Provisionning


Here we configure the Media Servers (MDS) for the phones.

In XiVO webi

  1. Go to Configuration -> Provisioning -> Template Line
  2. Create a template line per MDS (below the example for mds1):
    1. Unique name: <mdsX> (e.g. mds1) - note: it must be the same name as the one defined in section Define Media Servers
    2. Displayed Name: <Media Server X> (e.g. Media Server 1)
    3. Registrar Main: <VoIP IP of mdsX> (e.g.
    4. Proxy Main: <VoIP IP of mdsX> (e.g.

Media Servers connection to the XIVO database


The MDS need to connect to the XiVO database.

In file /var/lib/postgresql/11/main/pg_hba.conf add an authorization per mds to connect to the db. Here you will probably want to use the Data IP of mdsX:

host      asterisk    all      md5

And reload the database configuration:

xivo-dcomp reload-db

Media Server Configuration


On server2 install a Debian 9 with:

  • amd64 architecture,
  • en_US.UTF-8 locale,
  • ext4 filesystem
  • a hostname correctly set (files /etc/hosts and /etc/hostname must be coherent).

Before installing the MDS you have to have added:



The MDS installer will ask you:

  • the XiVO Data IP Address
  • the Media Server you’re installing (taken from the Media Server you declared at step Define Media Servers)
  • the Media Server Data IP
  • the Reporting Server IP

To install the MDS, download the XiVO installation script:

chmod +x

and run it:


Use -a switch to chose the same version as your XiVO (mds0)

./ -a 2020.07-latest

When prompted:

  • give the IP of XiVO (mds0): <XiVO Data IP> (e.g.
  • select the MDS you’re installing: <mdsX> (e.g. mds1)
  • enter the MDS Data IP: <mdsX Data IP> (e.g.
  • and finally the Reporting Server Data IP: <reporting Data IP) (e.g.


To finalize the MDS configuration you have to:

  1. Configure NTP to synchronize on XiVO (mds0) by replacing preconfigured servers/pools in file /etc/ntp.conf by:

    server iburst
  2. And restart NTP:

    systemctl restart ntp
  3. Create file /etc/asterisk/manager.d/02-xuc.conf to add permission for Xuc Server to connect with:

    • secret must be the same as the secret for xuc user on XiVO,

    • permit to authorize the VoIP IP of the Reporting Server

    • e.g.:

      cat > /etc/asterisk/manager.d/02-xuc.conf << EOF
      secret = muq6IWgNU1Z
      read = system,call,log,verbose,command,agent,user,dtmf,originate,dialplan
      write = system,call,log,verbose,command,agent,user,dtmf,originate,dialplan
      writetimeout = 10000
  4. Restart the services:

    xivo-service restart all

Outgoing Call Configuration

Create the Provider Trunk

Add on the XiVO the trunk towards your provider (it can be an ISDN or SIP trunk). When creating the trunk, select the Media Server on which it will be located.

Create Outgoing Call Rule


This outgoing call rule will handle outgoing call from XDS to Provider.

In XiVO Webi:

  1. Go to Services -> IPBX -> Call Management -> Outgoing calls
  2. Create a route for XDS:
    1. Call pattern: X.
    2. Trunks: <your provider trunk>
    3. (after opening the advanced form) Caller ID: <main DID of the system>

XiVO CC Configuration

On server3:

Enable WebRTC on MDS

WebRTC users can be configured on the MDS if you follow this manual procedure. These steps are to be done on the CTI Server (i.e. XiVO CC).

  1. First, create a directory /etc/docker/nginx/sip_proxy/ and the inside the file sip_proxy.conf:

    mkdir -p /etc/docker/nginx/sip_proxy/
    cd /etc/docker/nginx/sip_proxy/
    touch sip_proxy.conf
  2. Then edit this file sip_proxy.conf and add the following template section for each MDS on which there will be WebRTC users.

    location /ws-MDS_NAME {
       proxy_pass http://MDS_VOIP_IP:5039/ws;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       proxy_set_header Host $host;
       proxy_buffering off;
       proxy_connect_timeout 60m;
       proxy_read_timeout 60m;
       proxy_send_timeout 60m;
       keepalive_timeout 180s;
  3. Then replace:

    • MDS_NAME with mdsX (i.e. mds1, the technical name of your MDS)
    • MDS_VOIP_IP with the <VoIP IP of mdsX> (e.g.
  4. Then, you have to edit file docker-xivocc.yml, in /etc/docker/compose/ Add the highlighted line in the volumes section of the nginx service:

     - /etc/docker/nginx/sip_proxy:/etc/nginx/sip_proxy
  5. Finally, apply the changes on your nginx docker container:

    xivocc-dcomp up -d

Known Limitations

Agent states after XUC restart

Restarting XUC server with active calls in XDS environment will result in having some agents in incorrect state. Please see the note in restarting XUC server with active calls.