...
 
Commits (93)
......@@ -20,7 +20,7 @@ endif
envs/bin/sphinx-build:
python2.7 -mvirtualenv --system-site-packages envs
envs/bin/python envs/bin/pip install --use-wheel -U --cache-dir .cache/pip -I Pygments==2.2.0 setuptools==28.8.0 docutils==0.13.1 mock==1.0.1 pillow==2.6.1 "alabaster>=0.7,<0.8,!=0.7.5" commonmark==0.5.4 recommonmark==0.4.0 sphinx==1.5.3 "sphinx-rtd-theme<0.3" "readthedocs-sphinx-ext<0.6"
envs/bin/python envs/bin/pip install -U --cache-dir .cache/pip -I Pygments==2.2.0 "setuptools<41" docutils==0.13.1 mock==1.0.1 pillow==2.6.1 "alabaster>=0.7,<0.8,!=0.7.5" commonmark==0.5.4 recommonmark==0.4.0 sphinx==1.7.4 "sphinx-rtd-theme<0.3" "readthedocs-sphinx-ext<0.6"
envs/bin/python envs/bin/pip install --exists-action=w --cache-dir .cache/pip -rrequirements.txt
......
git+https://gitlab.com/xivo.solutions/sphinx-git.git@tagtitles
gitpython
sphinx_rtd_theme
......@@ -5,6 +5,10 @@ Proxy Configuration
If you use XiVO behind an HTTP proxy, you must do a couple of manipulations for
it to work correctly.
.. warning:: We do not recomend to use ``http_proxy`` environment variable. It may
break some services.
Instead you should configure the proxy on a per service basis as described
below.
apt
===
......@@ -14,6 +18,24 @@ Create the :file:`/etc/apt/apt.conf.d/90proxy` file with the following content::
Acquire::http::Proxy "http://domain\username:password@proxyip:proxyport";
dhcp-update
===========
*This step is needed if you use the DHCP server of the XiVO. Otherwise the DHCP configuration won't be correct.*
Proxy information is set via the :file:`/etc/xivo/dhcpd-update.conf` file.
Edit the file and look for the ``[proxy]`` section.
docker
======
When upgrading or installing XiVO it will attempt to download docker images.
For the proxy configuration, you need to create a systemd configuration file.
See Docker documentation: https://docs.docker.com/config/daemon/systemd/#httphttps-proxy
provd
=====
......@@ -21,14 +43,15 @@ Proxy information is set via the :menuselection:`Configuration --> Provisioning
page.
dhcp-update
===========
wget
====
*This step is needed if you use the DHCP server of the XiVO. Otherwise the DHCP configuration won't be correct.*
*This step is needed because this tool is used by xivo-upgrade script.*
Proxy information is set via the :file:`/etc/xivo/dhcpd-update.conf` file.
Create the :file:`~/.wgetrc` file with the following content::
Edit the file and look for the ``[proxy]`` section.
use_proxy=yes
http_proxy=http://username:password@proxyip:proxyport
xivo-fetchfw
......
......@@ -26,4 +26,5 @@ System
xivo-dird-phoned <xivo-dird-phoned>
xivo-purge-db <purge_logs>
xivo-service <service>
xivo-upgrade <xivo_upgrade_script>
xivo-sysconfd <xivo-sysconfd>
......@@ -79,19 +79,29 @@ It is possible to display customer information in an external web application us
* :menuselection:`Services > CTI Server > Sheets > Models`:
* Tab *General Settings*: Give a name
* Tab *Sheet*: You must define a sheet with two fields
* Tab *Sheet*: You must define a sheet with at least ``folderNumber`` and ``popupUrl`` fields set:
* ``folderNumber``
* ``folderNumber`` (MANDATORY)
* field type = ``text``
* It has to be defined. Can be calculated or use a default value not equal to "-"
* Note: You could leave "empty" using a whitespace (in hexadecimal: %20)
* ``popupUrl``
* ``popupUrl`` (MANDATORY)
* field type = ``text``
* The url to open when call arrives : i.e. http://mycrm.com/customerInfo?folder= the folder number will be automatically
appended at the end of the URL
* Additionally to the existing xivo variables, you can also use here the following variables(only available in Web Agent and Desktop Agent):
* ``{xuc-token}``: will be replaced by a token used for xuc websocket and rest api, for example ``http://mycrm.com/customerInfo?token={xuc-token}&folder=``
* ``{xuc-username}``: will be replaced by the username of the logged on user, for example ``http://mycrm.com/customerInfo?username={xuc-username}&folder=``
* ``multiTab`` (OPTIONAL)
* field type = ``text``
* set to the text ``true`` to open each popup in a new window.
* :menuselection:`Services > CTI Server > Sheets > Events`: Choose the right events for opening the URL (if you choose two events, url will opened twice etc.)
......
......@@ -230,6 +230,51 @@ For Firefox:
- add domain (without protocol) to the ``network.negotiate-auth.delegation-uris`` entry (ie. ``xuc.mydomain``).
- add domain (without protocol) to the ``network.negotiate-auth.trusted-uris`` entry (ie. ``xuc.mydomain``).
.. _cas-sso-configuration:
CAS SSO Authentication
=======================
To enable CAS authentication and single sign on feature, you need to have an existing CAS infrastructure. You need to be able to create a service for the XiVOCC environment.
.. warning::
The CAS authentication server must be accessible from the user and the server hosting the XiVOCC containers.
CAS Server users' username must match the XiVO username to allow login on the XiVOCC applications.
The CAS server must support at least CAS Protocol version 2.0.
XiVOCC Configuration
--------------------
* Edit the docker compose file ``/etc/docker/compose/docker-xivocc.yml`` to add the following configuration in the xuc section (use your CAS server URL instead of ``https://cas-server.example.org/cas`` and set ``CAS_LOGOUT_ENABLE`` to ``true`` if you want to logout from CAS when logging out from the application):
.. code-block:: dockerfile
xucmgt:
# ...
environment:
- CAS_SERVER_URL=https://cas-server.example.org/cas
- ...
# ...
xuc:
# ...
environment:
- CAS_SERVER_URL=https://cas-server.example.org/cas
- CAS_LOGOUT_ENABLE=false
- ...
# ...
* Recreate and start the XiVOCC environment:
.. code-block:: shell
xivocc-dcomp up -d
.. _nginx-trusted-certificate:
Install trusted certificate for nginx
......
......@@ -84,10 +84,15 @@ or::
"action":"none"
}
- ``action`` is one of ``"open"`` or ``"none"``
- ``event`` is one of ``"EventRinging"``, ``"EventEstablished"``, ``"EventReleased"``. The third party application will be opened when one the specified event occurs
- ``action`` is one of
- ``open``: Will open the given ``url`` inside the integration pane
- ``popup``: Will open the given ``url`` in a popup
- ``none``: No action will be performed
- ``event`` is one of ``EventRinging``, ``EventEstablished``, ``EventReleased``. The third party application will be opened when one the specified event occurs
- ``url`` should be the url to open inside the application. This url should point to a valid web application that can be specific for each call.
- ``autopause`` if set to true, the agent will be put on pause when the application pane is opened and back to ready when the application is completed.
- ``multitab`` if set to true and ``action`` is set to ``popup``, then the integration will be opened a in new popup window (or tab) each time instead of reusing the same window (or tab).
- ``title`` will set the title of the tabs that will be opened.
**Warning**, when the XucMgt application and the integrated application are on different server, domain, url,... (which should be common case), You may get CORS_ errors. To workaround this issue, you should implement the OPTIONS request on your web service. This method will be called by the browser before issuing the POST request to ensure the target web server allows calls from the original application. You application must set at least the following headers in order to overcome the CORS_ errors:
......
......@@ -99,6 +99,44 @@ where error_code is one of:
This token can then be used with the :ref:`CTI Authentication <cti_authentication>` and :ref:`rest_authentication_check`.
Obtain authentication token (SSO/CAS)
==========================================
GET http://localhost:$xucport/xuc/api/2.0/auth/cas?service=https://xucmgt.example.org&ticket=ST-11-Qsicgrh1mZ3dgoeOx7m6-af27d9025e0c
::
curl -XGET http://localhost:8090/xuc/api/2.0/auth/cas?service=https://xucmgt.example.org&ticket=ST-11-Qsicgrh1mZ3dgoeOx7m6-af27d9025e0c
Will retrieve an object
::
{login: "<login>", token: "<token>"}
or an error
::
{error:"<error_code>", message:"<error_message>"}
where error_code is one of:
* UserNotFound: User was authenticated using SSO but the corresponding user does not exist on XiVO
* CasServerUrlNotSet: XiVOCC containers are not configured (see :ref:`CAS SSO Authentication <cas-sso-configuration>`)
* CasServerInvalidResponse: The CAS server returned an invalid response
* CasServerInvalidParameter: The Parameters sent to the CAS Server are invalid
* CasServerInvalidRequest: The Request to the CAS server is invalid
* CasServerInvalidTicketSpec: The ticket specification is invalid
* CasServerUnauthorizedServiceProxy: The CAS service proxy is not authorized
* CasServerInvalidProxyCallback: The CAS service proxy callback is invalid
* CasServerInvalidTicket: The ticket is invalid (probably expired or defined for another service)
* CasServerInvalidService: The service is invalid
* CasServerInternalError: CAS Server internal error
* UnhandledError
This token can then be used with the :ref:`CTI Authentication <cti_authentication>` and :ref:`rest_authentication_check`.
.. _rest_authentication_check:
Check authentication token
......
......@@ -22,6 +22,36 @@ The XiVO Centralized User Management requires :
- see the next section for limitations on managed XiVOs.
.. _install_docker-ce:
Install Docker-CE
-----------------
.. important::
If you have docker proxy, please remove it from /etc/systemd/system/docker.service.d/mirror.conf, otherwise the installation will fail.
.. code-block:: bash
apt-get remove docker docker-engine docker.io
apt-get update
sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg2 \
software-properties-common
curl -fsSL https://download.docker.com/linux/$(. /etc/os-release; echo "$ID")/gpg | sudo apt-key add -
sudo add-apt-repository \
"deb [arch=amd64] https://download.docker.com/linux/$(. /etc/os-release; echo "$ID") \
$(lsb_release -cs) \
stable"
apt-get update
apt-get install docker-ce
.. _gcu_installation_requirements_for_xivos:
XiVO(s) Requirements & Limitations
......
......@@ -43,7 +43,7 @@ import os
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.todo', 'sphinx_git', 'sphinx.ext.graphviz']
extensions = ['sphinx.ext.todo', 'sphinx.ext.graphviz']
graphviz_output_format = 'svg'
# Add any paths that contain templates here, relative to this directory.
......
......@@ -137,7 +137,7 @@ A notification is also shown to display pending callbacks in menu to know status
On this page, the agent only has access to basic information about the callback: activity and due date,
On the left of each callback line, a colored clock indicates the temporal status of this callback:
- `yellow` if the callback is to be processed later
- `blue` if the callback is to be processed later
- `green` if we are currently inside the callback period
- `red` if the callback period is over
......
......@@ -52,16 +52,21 @@ and both queues (name and number) under column **File** in one recording.
Stop recording upon external transfer
-------------------------------------
Recording is stopped when both parties of the call are external.
Recording is stopped when an incoming call is transferred to an external number:
For example if an external incoming call is recorded and if, at some point, it is transferred to an external party,
as soon as the transfer is completed, the recording of the incoming call will be stopped.
In the same way if an internal user makes an outgoing call which is recorded and then transfers it to another external party,
as soon as the transfer is completed, the recording of the outgoing call will be stopped.
* Given a **external incoming call** which is **recorded**,
* If this call is transferred to an external number (via the phone or the UC Assistant or the CC Agent),
* Then, as soon as the transfer is completed, the recording of the **incoming call** will be stopped.
This behavior can be deactivated, see :ref:`configuration section <stop_recording_upon_ext_xfer_conf>`.
.. note:: **Limitations:**
Note that this feature is not intended to work if outgoing calls are recorded. In this case:
* if an external incoming call is transferred to an external number, only the incoming call recording will be stopped. The outgoing call recording won't be stopped.
* if an outgoing call is transferred to another outgoing call, the recording won't be stopped.
Recording filtering
===================
......
......@@ -102,6 +102,11 @@ xivo-aastra-4.3.0
Particularly these new firmwares support forwarding of Multiple Spanning Tree Protocol (MSTP) messages from the LAN port to the PC port.
This ensures issues regarding network loops are not created.
xivo-cisco-spa8000-6.1.11
-------------------------
:v1.1: Fix download of firmware with procedure :ref:`Cisco SPA8000 download firmware <cisco-spa8000-fw-download>`.
xivo-patton-6.10
----------------
......@@ -179,6 +184,10 @@ xivo-yealink-v81
.. note:: Replaces xivo-yealink-v80 plugin
:v2.5.0: add XiVO logo for T46G/S and T48G/S
:v2.4.3: fix firmware downloading
:v2.4.2: add provisioning of T27G in firmware v81
:v2.4.1: add provisioning of W52P in firmware v81
:v2.3: switch to default Yealink french translation to fix duplicate label for T48X
.. note:: It leads to several small differences in the labels, for example:
......@@ -213,3 +222,23 @@ xivo-yealink-v81
apt-get update
apt-get install unrar
xivo-yealink-v84
----------------
.. note:: Replaces xivo-yealink-v81 plugin for Yealink T4XS models (and others, see plugin info)
:v1.2: fix answering of second call from UC Assistant or CC Agent
:v1.1: first version of the plugin for fw v84
.. note:: What's new from v81 plugin:
* Small differences for some french labels, for example:
* *Mtr Att* is changed to *Attente*
* *Historique* is changed to *Récents*
* *Répertoires* is changed to *Annuaire*
* New *Station name* with first line display name and number
* XiVO logo for T46S and T48S
* Admin default password was changed
......@@ -37,7 +37,7 @@ Aastra
------
Aastra has been acquired by Mitel in 2014. In XiVO, the 6700 series and 6800 series phones are still
referenced as Aastra phones, for historical and compatibility reasons.
referenced as Aastra phones, for historical and compatibility reasons. There is no evolution or maintenance currently planned for these models.
6700i series
......@@ -310,6 +310,27 @@ must be changed. You can read the :ref:`fax-analog-gateway` section.
* *XIVO_IP* is the IP address of your XiVO,
* *CONF_FILE* is one of ``spa3102.cfg``, ``spa8000.cfg``
.. _cisco-spa8000-fw-download:
**Cisco SPA8000 Firmware Download Procedure**
To install Cisco SPA8000 firmware, you need to manually download
the firmware files from the Cisco website and save them in the
:file:`/var/lib/xivo-provd/plugins/xivo-cisco-spa8000-6.1.11/var/cache` directory.
This directory is created by XiVO when you install the plugin (i.e. xivo-cisco-spa8000-6.1.11).
If you create the directory manually, the installation will fail.
* Go to https://software.cisco.com/
* Go to "Software download"
* In the search bar, search for "SPA8000"
* Click on "Analog Telephone Adaptor (ATA) Firmware"
* Then select under "All Release" the "6" menu, and under the "6" menu, select release "**6.1.11**"
* Finally download the file "**SPA8000_6.1.11_FW.zip**"
* Copy this file into the :file:`/var/lib/xivo-provd/plugins/xivo-cisco-spa8000-6.1.11/var/cache` directory
* Lastly, in the XiVO XiVO web interface, edit the plugin xivo-cisco-spa8000 and you'll then be able to click on the "install" button for the firmware
Cisco 7900 Series
^^^^^^^^^^^^^^^^^
......@@ -442,7 +463,7 @@ The procedure is similar for the network locale and the user locale package, but
Mitel
-----
The Mitel 6700 Series and 6800 Series SIP Phones are supported in XiVO. See the Aastra_ section.
Some Mitel 6700 Series and 6800 Series SIP Phones are supported in XiVO. See the Aastra_ section for supported devices.
Patton
......@@ -876,7 +897,12 @@ Yealink
| Paging | N | N | Y | Y | Y | Y | NYT | Y | Y | NYT | N | Y | Y | NYT | Y | NYT | Y | NYT | Y | NYT | N |
+--------------------------------------------+------+---------+------+------+---------+------+------+------+------+---------+------+------+------+------+------+------+------+------+------+------+------+
See also the list of :ref:`community supported Yealink models <yealink-community-devices>`.
Particularities:
* For plugin xivo-yealink-v84, default password is **9486** (i.e. the word "xivo" on a telephone keypad).
* See also the list of :ref:`community supported Yealink models <yealink-community-devices>`.
Regarding the W52P (DECT), there is firmware for both the base station and the handset. The base and the
handset are `probably going to work if they are not using the same firmware version
......
......@@ -4,12 +4,18 @@
XiVO Solutions |version| Documentation (Aldebaran Edition)
**********************************************************
.. important:: **What's new in this version ?**
.. warning:: This version is still in development and not yet released.
You should refer to current LTS `XiVO Polaris documentation <https://documentation.xivo.solutions/en/2017.11/>`_.
* XiVO administration web interface has been revamped to make it lighter and more responsive.
* UC assistant can handle conferences with features such as showing participants, including a visual indicator to show who is talking. Added also possibility to Mute/Unmute/Kick participants if you're an organizer of the conference.
* Personal contacts can be managed now from UC assistant. Possibility to add/edit/delete/import your own contacts from the application.
See :ref:`aldebaran_release` page for the complete list of **New Features** and **Behavior Changes**.
.. note:: For previous LTS version, see `XiVO Polaris documentation <https://documentation.xivo.solutions/en/2017.11/>`_.
.. figure:: logo_xivo.png
:scale: 30%
:scale: 70%
XiVO solutions developed by Avencall_ is a suite of PBX applications based on several free existing components including Asterisk_
and our own developments. This powerful and scalable solution offers a set of features for corporate telephony and call centers to power their business.
......
......@@ -26,13 +26,6 @@ XiVO Installation & Upgrade
xivo/xivouc/xivouc
**XiVO Swarm**
.. toctree::
:maxdepth: 1
xivo/xivoorchestration/xivoorchestration
**Upgrading**
.. toctree::
......
......@@ -22,8 +22,8 @@ Installing from the ISO image
.. note:: Our ISO image does not support UEFI system
* Download the ISO image. (`latest version`_) (`all versions`_)
* Boot from the ISO image, select ``Install`` and follow the instructions. You must select a locale
with charset UTF-8.
* Boot from the ISO image, select ``Install`` and follow the instructions. You must select locale
``en_US.UTF-8``.
* At the end of the installation, you can continue by running the :ref:`configuration
wizard. <configuration_wizard>`
......@@ -39,10 +39,10 @@ Otherwise GPG key of XiVO repository will not be installed and must be added man
Installing from a minimal Debian installation
=============================================
XiVO can be installed directly over a **64-bit** Debian jessie. When doing so, you are strongly
advised to start with a clean and minimal installation of Debian jessie.
XiVO can be installed directly over a **64-bit** Debian **Jessie**. When doing so, you are strongly
advised to start with a clean and minimal installation of Debian **Jessie**.
The latest installation image for Debian jessie can be found at https://www.debian.org/releases/jessie/debian-installer.
The latest installation image for Debian **Jessie** can be found at https://www.debian.org/releases/jessie/debian-installer.
Requirements
......@@ -51,7 +51,7 @@ Requirements
The installed Debian must:
* use the architecture ``amd64``
* have a default locale with charset UTF-8
* have a default locale ``en_US.UTF-8``
.. note:: In case you want to migrate a XiVO from ``i386`` to ``amd64``, see :ref:`migrate_i386_to_amd64`.
......@@ -67,7 +67,7 @@ it executable::
And run it::
./xivo_install.sh
./xivo_install.sh -a 2018.05-latest
At the end of the installation, you can continue by running the :ref:`configuration
wizard. <configuration_wizard>`
......
.. _upgrade:
*********
Upgrading
*********
*******
Upgrade
*******
Upgrading a *XiVO PBX* is done by executing commands through a terminal on the
server. You can connect to the server either through SSH or with a physical
console.
server.
.. note:: Downgrade is not supported
Overview
========
To upgrade your *XiVO PBX*, you have to use both ``xivo-dist`` and :ref:`xivo-upgrade <xivo-upgrade_script>` tools.
These tools handle the process of upgrading:
The upgrade consists of the following steps:
* the system (Debian packages)
* and the *XiVO PBX* packages
* switch the version via ``xivo-dist`` utility
* upgrade via the ``xivo-upgrade`` utility: it will upgrade the system (Debian packages) and the *XiVO PBX* packages
.. warning:: The following applies to *XiVO PBX* **>= 2016.03**. For older version, see :ref:`version_specific_upgrade` section.
Preparing the upgrade
=====================
There are two cases:
#. :ref:`Upgrade to an LTS version of XiVO PBX <upgrade_latest_version_xpbx>`,
#. :ref:`Upgrade to an Intermediate version of XiVO PBX <upgrade_specific_version_xpbx>`,
#. :ref:`Upgrade to another LTS XiVO PBX version <upgrade_to_lts_version_xpbx>`,
#. :ref:`Upgrade to the latest Bugfix release <upgrade_latest_ltsbugfixrel_xpbx>` of your current installed LTS version.
.. warning:: Note that it is not possible to downgrade to any version.
.. _upgrade_to_lts_version_xpbx:
Upgrade to another LTS version
------------------------------
To prepare the upgrade you should:
#. Switch the sources to the new XiVO PBX **LTS** version with ``xivo-dist``, for example, to switch to Aldebaran LTS version::
xivo-dist xivo-aldebaran
#. **Read carefully the** :ref:`xivosolutions_release` starting from your current version to the version you target (read **even more
carefully** the New features and Behavior changes between LTS)
#. **Check** the specific instructions and manual steps *from your current LTS to your targetted LTS* and all intermediate LTS: see :ref:`upgrade_lts_manual_steps`
#. **Check also** if you are in a specific setup that requires a :ref:`specific procedure <upgrade_specific_proc>`
to be followed (e.g. :ref:`upgrading-a-cluster`).
#. And then upgrade, see `Upgrading`_
.. _upgrade_latest_version_xpbx:
Upgrade to an **LTS** version
-----------------------------
.. _upgrade_latest_ltsbugfixrel_xpbx:
To upgrade to a XiVO PBX **LTS** version you have to update the sources list by using the `xivo-dist` command::
Upgrade to latest Bugfix release of an LTS version
--------------------------------------------------
xivo-dist <XiVO LTS VERSION>
After the release of an **LTS** *version* (e.g. *Polaris*) we may backport some bugfixes in this version.
We will then create a **subversion** (e.g. Polaris **.04**) shipping these bugfixes.
These bugfix version does not contain any behavior change.
Currently there are two XiVO PBX **LTS** versions:
To upgrade to the **latest subversion** of your current installed *version* you need to:
#. (**latest**) XiVO Polaris (2017.11) - released 2017/10/09::
#. **Read carefully the** :ref:`xivosolutions_release` starting from your installed version (e.g. Polaris.00) to the latest bugfix release (e.g. Polaris.04).
#. Verify that the debian sources list corresponds to your *installed LTS* or refix it, for example for Polaris::
xivo-dist xivo-polaris
#. (*old*) XiVO Five (2017.03) - released 2017/04/03: see `XiVO Five documentation
<https://documentation.xivo.solutions/projects/five>`_.
#. And then upgrade, see `Upgrading`_
.. _upgrade_specific_version_xpbx:
Upgrading
=========
Upgrade to an **Intermediate** version
--------------------------------------
.. note:: About `xivo-upgrade` script usage see :ref:`xivo-upgrade_script`
.. note:: **Intermediate** versions have a limited support. You should install LTS version only.
After having prepared your upgrade (see above), you can upgrade:
Between XiVO PBX LTS versions we release **Intermediate** versions (to which is given a limited support). To upgrade to a *specific* **Intermediate** version, you have to update the sources to point to this *specific* version. You have to do it with the ``xivo-dist`` command. For example, if you want to upgrade to **2017.06**::
#. When ready, launch the upgrade process. **All XiVO PBX services will be stopped during the process**::
xivo-dist xivo-2017.06-latest
xivo-upgrade
#. Download the new config-mgt service::
Preparing the upgrade
=====================
xivo-dcomp pull
To prepare the upgrade you should:
#. Upgrade the config-mgt service::
#. **Read carefully the** :ref:`xivosolutions_release` **starting from your current version to the version you target.**
#. Check if you are in a specific setup that requires a :ref:`specific procedure <upgrade_specific_proc>`
to be followed (e.g. :ref:`upgrading-a-cluster`).
#. Finally, you can download the packages beforehand by running ``xivo-upgrade -d``. This is not mandatory,
but it does not require stopping any service, so it may be useful to reduce the downtime of the server
while upgrading.
xivo-dcomp up -d
Upgrade
=======
Post Upgrade
============
.. note:: About `xivo-upgrade` script see:
When finished:
.. toctree::
:maxdepth: 2
* Check that all services are running::
xivo_upgrade_script
xivo-service status all
* Check that all the docker services are in the correct version. Compare the output of ``xivo-dcomp version`` with the table in :ref:`xivosolutions_release`
* Check that services are correctly working like SIP registration, ISDN link status,
internal/incoming/outgoing calls, XiVO Client connections etc.
#. For custom setups, follow the required procedures described below (e.g. :ref:`upgrading-a-cluster`).
#. When ready, launch the upgrade process. **All XiVO PBX services will be stopped during the process**::
xivo-upgrade
.. _upgrade_lts_manual_steps:
Manual steps for LTS upgrade
============================
.. toctree::
:maxdepth: 1
#. When finished, check that all services are running (the list is displayed at the end of the upgrade).
#. Check that services are correctly working like SIP registration, ISDN link status,
internal/incoming/outgoing calls, XiVO Client connections etc.
upgrade_from_five_to_polaris
upgrade_from_polaris_to_aldebaran
.. _upgrade_specific_proc:
......
***********************
Upgrade Five to Polaris
***********************
In this section are listed the manual steps to do when migrating from Five to Polaris.
Before Upgrade
==============
On XiVO PBX
-----------
Follow the :ref:`upgrade` page.
On XiVO CC
----------
The *xivo-solutions-VERSION* no longer exists. The ``xivocc-installer`` package is now located in *xivo-VERSION* distribution.
You have to update your source list accordingly.
#. Remove apt source list file::
rm /etc/apt/sources.list.d/xivo-solutions.list
#. Add new source list file::
echo "deb http://mirror.xivo.solutions/debian xivo-polaris main" > /etc/apt/sources.list.d/xivo-dist.list
After Upgrade
=============
On XiVO PBX
-----------
* Accept new cel.conf: if you are asked by ``xivo-upgrade`` installer, you must choose to replace the ``cel.conf`` file or ensure
that its content correspond to these :ref:`defaults <cel>`.
* Finish to remove xivo-ctid-ng and xivo-websocketd::
apt-get purge xivo-websocketd xivo-ctid-ng
* Add `writetimeout` parameter to the the :file:`/etc/asterisk/manager.d/02-xivocc.conf` file:
.. code-block:: bash
:emphasize-lines: 7
[xuc]
secret = ...
deny = ...
permit = ...
read = ...
write = ...
writetimeout = 10000
* You **MUST** update:
* *Snom* phones to use plugin version **>=2.2** to be able to use CTI Transfer (UC Assistant or CCAgent),
* *Yealink* phones to use plugin with **v81** firmware to be able to use CTI Transfer (UC Assistant or CCAgent).
* The WebRTC call limit was raised to 2 (to enable transfers). The simultcalls parameter of a WebRTC user should be set to 2 also.
On XiVO CC
----------
* Update new fingerboard::
xivocc-dcomp stop fingerboard
docker rm xivocc_fingerboard_1
xivocc-dcomp up -d
* SpagoBI:
* **Import new reports** as described in :ref:`spagobi` post install step
* Then, you should also remove old sample reports:
* Go to `Reports` menu and delete all reports which are located under **Racine -> Sample**
* Once all reports are deleted inside these folder you can go to `Functionalities Management` menu as shown in following
screenshot:
.. figure:: reportsdelete1.png
:scale: 100%
* From here, you can delete empty folders by clicking on it
.. figure:: reportsdelete2.png
:scale: 100%
* At the end you should have a report folder list, that contains only `Rapports` and `Accueil` folder as seen here (unless
you have some specific customer report):
.. figure:: reportslist.png
:scale: 100%
......@@ -2,7 +2,7 @@
Upgrade Polaris to Aldebaran
****************************
In this section is listed the manual steps to do when migrating from Polaris to Aldebaran.
In this section are listed the manual steps to do when migrating from Polaris to Aldebaran.
Before Upgrade
......@@ -35,9 +35,7 @@ On XiVO PBX
On XiVO CC
----------
* Update distribution to xivo-aldebaran in source list::
echo "deb http://mirror.xivo.solutions/debian xivo-aldebaran main" > /etc/apt/sources.list.d/xivo-dist.list
Nothing specific, follow the :ref:`upgrade_cc` page.
After Upgrade
......@@ -57,6 +55,9 @@ On XiVO PBX
For example an outgoing redirection towards "my_outcall (@to-extern)" to number "0123456789"
can be replaced by an extension redirection to "0123456789" with context "to-extern"
* Callbacks: callback API URL was changed. It is now prefixed with `configmgt`. If you have any AGI calling the callbacks API
(for example `api/1.0/callback_lists`) you MUST add the prefix `configmgt` to it : `configmgt/api/1.0/callback_lists`.
* ConfigMgt service was moved to XiVO PBX. Here's how to migrate the ConfigMgt database:
* On your **XiVO CC** (where the service pgxivocc is run) authorize user root to login with password via ssh,
......
******************
XiVO Orchestration
******************
This page describes how to install XiVO orchestration and how to use it.
The orchestration is done using Docker and its built-in multi-host and multi-container orchestration called **Swarm**.
Prerequisites
=============
.. important::
Your **XiVO PBX** server **MUST** meet the following requirements:
- A swarm manager, which can be your **XiVO PBX** server
- A swarm worker, which can be your **XiVO CC** server
- OS : Debian 8 (jessie), **64 bits**
- **4 GB of RAM**
- 4-core CPU
- 20 GB of free disk space
- you have a *XiVO PBX* installed in a compatible version
- the *XiVO PBX* **is setup** (wizard must be passed) with users, queues and agents, you must be able to place and answer calls
Install process overview
========================
The configuration and deployment is handled by ``xivo-orchestration`` package, which does not come with the XiVO installation.
This package must be installed manually.
The join and leave swarm actions on worker are handled by the script ``xivo-worker-node`` which comes together with ``xivocc-installer`` package.
The deployment consist of minimum 1 manager and minimum 1 worker.
Manager
-------
The swarm initialization is done on the manager which the workers are joining to or leaving from.
The swarm manager can start and stop the services and in XiVO environment the manager will be *XiVO PBX*.
Worker
------
The swarm worker can join or leave the swarm network and behaves passively in terms of swarm management.
.. important::
Your worker may have ``xivocc-installer`` installed, but must not be running any **XiVO CC** components.
All docker containers must be removed before the swarm installation. And the ``xivocc-dcomp`` script must not
be used to start any containers.
Preparation beforehand
======================
- Note XiVO AMI secret from ``/etc/asterisk/manager.d/02-xivocc.conf`` or generate one
.. code-block:: bash
< /dev/urandom tr -dc A-Za-z0-9 | head -c${1:-11} | xargs echo
- On the node running the database (XuC), create the database folder
.. code-block:: bash
mkdir -p /var/lib/postgresql/data
- Gather the hostnames of your nodes, which will be needed during the first run configuration.
Every node must use its unique hostname that will be used in configuration dialogs.
- Create folder for logs on **all** nodes:
.. code-block:: bash
mkdir -p /var/log/xivocc
chown -R daemon:daemon /var/log/xivocc
- On your worker nodes, install ``Docker-CE``, please follow the instructions:
.. _install_docker-ce:
Install Docker-CE
-----------------
.. important::
If you have docker proxy, please remove it from /etc/systemd/system/docker.service.d/mirror.conf, otherwise the installation will fail.
.. code-block:: bash
apt-get remove docker docker-engine docker.io
apt-get update
sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg2 \
software-properties-common
curl -fsSL https://download.docker.com/linux/$(. /etc/os-release; echo "$ID")/gpg | sudo apt-key add -
sudo add-apt-repository \
"deb [arch=amd64] https://download.docker.com/linux/$(. /etc/os-release; echo "$ID") \
$(lsb_release -cs) \
stable"
apt-get update
apt-get install docker-ce
Configure XiVO orchestration
============================
Manager
-------
On *XiVO PBX*, install the ``xivo-orchestration`` package.
.. code-block:: bash
apt-get install xivo-orchestration-service
Run and follow the instructions on dialog screens.
.. code-block:: bash
xivo-orchestration start
Copy the worker token after successful swarm manager initialization.
.. code-block:: bash
docker swarm join-token worker | grep token | awk '{ print $5 }'
SpagoBI
^^^^^^^
Edit the compose file for the chosen installation, find section ``spagobi`` and replace ``${REPORTING_HOST}`` with
IP address of the node with SpagoBI.
.. code-block:: bash
- JAVA_OPTS=-Dexternal.host=REPORTING_HOST_IP
PostgresSQL
^^^^^^^^^^^
Then reload PostgreSQL configuration and start the swarm.
.. code-block:: bash
/etc/init.d/postgresql restart
XiVO-UC
^^^^^^^
If you chose to install XiVO UC on a single node, you must manually remove the ``nginx`` section from the
``/etc/docker/swarm/xivo-compose-xivouc.yml`` compose file.
Worker
------
Go to your swarm worker, which can be any available machine with ``xivocc-installer`` installed:
.. code-block:: bash
xivo-worker-node join
Enter the worker token from previous step when prompted.
or without ``xivocc-installer`` installed:
.. code-block:: bash
docker swarm join --token SWARM_TOKEN MANAGER_IP:2377
Repeat this step in case you have more workers.
Nginx
^^^^^
Go to your worker node with XUC and install certificates for the xivoxc_nginx container.
.. code-block:: bash
SSLDIR=/etc/docker/nginx/ssl
mkdir -p $SSLDIR
openssl req -nodes -newkey rsa:2048 -keyout $SSLDIR/xivoxc.key -out $SSLDIR/xivoxc.csr -subj "/C=FR/ST=/L=/O=Avencall/OU=/CN=$(hostname --fqdn)"
openssl x509 -req -days 3650 -in $SSLDIR/xivoxc.csr -signkey $SSLDIR/xivoxc.key -out $SSLDIR/xivoxc.crt
openssl x509 -req -days 3650 -in $SSLDIR/xivoxc.csr -signkey $SSLDIR/xivoxc.key -out $SSLDIR/xivoxc.crt
SpagoBI
^^^^^^^
Go to your worker node with **spagobi** and create a subfolder for logs:
.. code-block:: bash
mkdir -p /var/log/xivocc/spagobi
chown -R daemon:daemon /var/log/xivocc
Recording
^^^^^^^^^
Go to your worker node with **recording** and create a folder for recordings:
.. code-block:: bash
mkdir /var/spool/recording-server
.. important::
Wait a few seconds for all services come up on each worker. The services should be running on the workers and manager as
configured in the swarm configuration dialog.
After-install steps
===================
In order to use configmgt and xuc server without IP access, an authorization token is required.
Navigate to ``XiVO Web Interface - Configuration - Management - Web Services Access`` and edit the ``xivows`` user.
On tab ``ACL`` create an ACL with value ``#`` and save the form.
To generate the token:
.. code-block:: bash
curl -X POST --header 'Content-Type: application/json' \
--header 'Accept: application/json' \
-u xivows:xivows \
-d '{
"backend": "xivo_service",
"expiration": 5656565600
}' \
--insecure 'https://IP_OF_YOUR_XIVO:9497/0.1/token'
Add this token to the ``custom.env`` as ``XIVO_CONFD_AUTH_TOKEN=token`` on manager node.
Verify the deployment
=====================
.. important::
The docker images, if not already present on the nodes, are downloading silently in the background.
1. You can see the status of the services on each node by navigating to
.. code-block:: bash
http://YOUR_MANAGER_IP:8080
To check whether the services were correctly deployed and the worker(s) are connected to the swarm check on each:
Manager
-------
.. code-block:: bash
docker node ls
Should list minimum 1 manager and 1 worker.
.. code-block:: bash
docker service ls
Should list all XiVO CC components running as services.
.. code-block:: bash
docker ps
Should list all XiVO CC components running on this manager.
Worker
------
.. code-block:: bash
docker ps
Should list all XiVO CC components running on this worker.
......@@ -109,6 +109,7 @@ Uninstallation consists of these steps:
#. purge the xivouc package: ``apt-get purge xivouc``
#. install the default nginx configuration: ``apt-get install xivo-nginx-cfg``
#. remove docker network: ``docker network rm xivocc_default``
.. warning::
Do not purge the ``xivouc-installer`` package! It is required by XiVO.
......@@ -184,6 +184,9 @@ Also, check that you have following information:
* Number of weeks to keep statistics;
* Number of weeks to keep recordings (beware of space disk);
The number of weeks to keep statistics **must be higher** than the number of weeks to keep recordings.
Recording purging is based on the statistic data, so the statistic data must not be removed before purging recordings.
Install the *xivocc-installer* package via *apt*:
#. Create the xivo sources list file :file:`/etc/apt/sources.list.d/xivo-dist.list` and add the following line
......@@ -260,7 +263,7 @@ The various applications are available on the following addresses:
- Xuc-related applications: http://192.168.0.2:8070/
- SpagoBI: http://192.168.0.2:9500/
- Config Management: http://192.168.0.2:9100/
- Config Management: http://<XiVO IP Address>:9100/configmgt/
- Recording server: http://192.168.0.2:9400/
- Kibana: http://192.168.0.2/
......@@ -270,7 +273,7 @@ Post Installation
User Configuration
------------------
You should configure users and their rights in the Configuration manager http://192.168.0.2:9100/ (default user
You should configure users and their rights in the Configuration manager http://<XiVO IP Address>:9100/configmgt/ (default user
avencall/superpass).
.. warning::
......
......@@ -203,6 +203,9 @@ During the installation, you will be asked for :
- the number of weeks to keep for the recording files
- the external IP of the machine (i.e. the adress used afterwards for http URLs)
The number of weeks to keep statistics **must be higher** than the number of weeks to keep recordings.
Recording purging is based on the statistic data, so the statistic data must not be removed before purging recordings.
Create the following alias in your .bashrc file:
.. code-block:: bash
......@@ -263,7 +266,6 @@ List XivoCC services :
# dcomp ps
Name Command State Ports
---------------------------------------------------------------------------------------------------------------------
xivocc_config_mgt_1 bin/config-mgt-docker Up 0.0.0.0:9100->9000/tcp
xivocc_elasticsearch_1 /docker-entrypoint.sh elas ... Up 0.0.0.0:9200->9200/tcp, 0.0.0.0:9300->9300/tcp
xivocc_fingerboard_1 /bin/sh -c /usr/bin/tail - ... Up
xivocc_kibana_volumes_1 /bin/sh -c /usr/bin/tail - ... Up
......
......@@ -77,7 +77,6 @@ The list of the services launched should look like :
# xivocc-dcomp ps
Name Command State Ports
---------------------------------------------------------------------------------------------------------------------
xivocc_config_mgt_1 bin/config-mgt-docker Up 0.0.0.0:9100->9000/tcp
xivocc_elasticsearch_1 /docker-entrypoint.sh elas ... Up 0.0.0.0:9200->9200/tcp, 0.0.0.0:9300->9300/tcp
xivocc_fingerboard_1 /bin/sh -c /usr/bin/tail - ... Up
xivocc_kibana_volumes_1 /bin/sh -c /usr/bin/tail - ... Up
......
.. _upgrade_cc:
*******
Upgrade
*******
Upgrading a *XiVO CC* is done by executing commands through a terminal on the
server.
.. note:: Downgrade is not supported
Overview
========
The following components will be upgraded :
The upgrade consists of the following steps:
- Docker images
- xivocc-installer package
* switch/verify the version in the debian sources list
* update of the ``xivocc-installer`` package
* update of the Docker images
.. warning:: This upgrade procedure applies only to XiVO CC installed via the ``xivocc-installer`` package.
Preparing the upgrade
=====================
Before upgrading you have to check or change your sources list.
It should be located in the file :file:`/etc/apt/sources.list.d/xivo-dist.list`.
There are three cases:
#. :ref:`Upgrade to an LTS XiVO CC version <upgrade_latest_version_xcc>`,
#. :ref:`Upgrade to an Intermediate version <upgrade_specific_version_xcc>`,
#. :ref:`Upgrade to the latest subversion <upgrade_latest_subversion_xcc>` of your current installed version.
.. warning:: Note that it is not possible to downgrade to any version.
.. _upgrade_latest_version_xcc:
Upgrade to an **LTS** version
-----------------------------
Currently XiVO CC *latest* **LTS** version is Polaris and is the numeric release 2017.11. To upgrade to the latest version the sources list must point towards *debian* URI and *xivo-polaris* suite::
deb http://mirror.xivo.solutions/debian/ xivo-polaris main
or point towards *archive* URI and *xivo-2017.11-latest* suite::
deb http://mirror.xivo.solutions/archive/ xivo-2017.11-latest main
There are two cases:
#. :ref:`Upgrade to another LTS XiVO CC version <upgrade_to_lts_version_xcc>`,
#. :ref:`Upgrade to the latest Bugfix release <upgrade_latest_ltsbugfixrel_xcc>` of your current installed LTS version.
.. _upgrade_specific_version_xcc:
Upgrade to an **Intermediate** version
--------------------------------------
.. _upgrade_to_lts_version_xcc:
.. note:: **Intermediate** versions have a limited support. You should install LTS version only.
Upgrade to another LTS version
------------------------------
Between two LTS versions we release **Intermediate** versions (to which is given a limited support). To upgrade to a *specific* **Intermediate** version the sources list must point towards *archive* URI and *xivo-VERSION-latest* suite.
To upgrade to another XiVO Solution **LTS**:
For example if you want to upgrade to **2017.06** version you should have::
#. Switch the debian sources to the targetted **LTS** version (it should be located in the file :file:`/etc/apt/sources.list.d/xivo-dist.list`). For example, to switch to Aldebaran LTS version::
deb http://mirror.xivo.solutions/archive/ xivo-2017.06-latest main
deb http://mirror.xivo.solutions/debian/ xivo-aldebaran main
Note the ``/archive/`` and ``-2017.06-latest`` above.
#. **Read carefully the** :ref:`xivosolutions_release` starting from your current version to the version you target (read **even more
carefully** the New features and Behavior changes between LTS)
#. **Check** the specific instructions and manual steps *from your current LTS to your targetted LTS* and all intermediate LTS: see :ref:`upgrade_lts_manual_steps`
#. **Check also** if you are in a specific setup that requires a :ref:`specific procedure <upgrade_specific_proc_xcc>`
#. And then upgrade, see `Upgrading`_
.. _upgrade_latest_subversion_xcc:
.. _upgrade_latest_ltsbugfixrel_xcc:
Upgrade to latest **subversion**
--------------------------------
Upgrade to latest Bugfix release of an LTS version
--------------------------------------------------
.. important:: For version older than Five (2017.03), see `XiVO Five documentation <https://documentation.xivo.solutions/projects/five>`_
After the release of a *version* (e.g. *Polaris (2017.11)*) we may backport some bugfixes in this version.
We will then create a **subversion** (e.g. Polaris **.04** (2017.11 **.04**)) shipping these bugfixes.
These bugfix version does not contain any behavior change.
After the release of a *version* (e.g. *2017.11*) we may backport some bugfixes in this version.
We will then create a **subversion** (e.g. 2017.11 **.01**) shipping these bugfixes.
To upgrade to the **latest subversion** of your current installed *version* you need to:
#. **Read carefully the** :ref:`xivosolutions_release` starting from your installed version (e.g. Polaris.00) to the latest bugfix release (e.g. Polaris.04).
#. Verify that the debian sources list corresponds to your *installed LTS* (it should be located in the file :file:`/etc/apt/sources.list.d/xivo-dist.list`)
#. Verify that the :file:`/etc/docker/compose/factory.env` file has
#. ``XIVOCC_TAG=VERSION`` (where ``VERSION`` is your current installed *version* - e.g. *2017.11*)
#. and ``XIVOCC_DIST=latest``
#. Then update the images with ``xivocc-dcomp pull`` command,
#. And upgrade the containers with ``xivocc-dcomp up -d`` command.
* ``XIVOCC_TAG=VERSION`` (where ``VERSION`` is your current installed *version* - e.g. *2017.11*)
* and ``XIVOCC_DIST=latest``
#. And then upgrade, see `Upgrading`_
Preparing the upgrade
=====================
Upgrading
=========
To prepare the upgrade you should:
After having prepared your upgrade (see above), you can upgrade:
#. Read :ref:`xivosolutions_release` starting from your version to the version you target.
Upgrade
=======
When you have checked the sources.list you can upgrade with the following commands::
#. When you have checked the sources.list you can upgrade with the following commands::
apt-get update
apt-get install xivocc-installer
The current ``docker-compose.yml`` file will be renamed to ``docker-compose.yml.dpkg-old`` and new template downloaded.
A new ``docker-compose.yml`` file will be rendered from the template using the current xivocc version.
Then you have to:
#. Download the new images::
#. If there is any change, you should accept the new :file:`docker-compose.yml` file. Then compare it with the old :file:`docker-compose.yml.dpkg-old` file and report in the new any specific configuration.
#. Then download the new docker images::
xivocc-dcomp pull
#. And run the new container (**All XiVO CC services will be restarted**)::
#. And run the new containers (**Corresponding XiVO CC services will be restarted**)::
xivocc-dcomp up -d
......@@ -110,71 +94,32 @@ Then you have to:
Post Upgrade
============
Check your upgrade through :ref:`check-list`.
Upgrade notes
=============
See :ref:`xivosolutions_release` for version specific informations.
Reporting Upgrade notes
=======================
These notes include upgrade procedures for old versions of the **Pack reporting**, before **XivoCC** starts and before it was packaged with Docker.
In those cases, run the following command to find the installed version of the pack reporting:
.. code-block:: bash
dpkg -l|grep pack-reporting
From version < 1.6
------------------
When finished:
* data retention time will be lost during upgrade : save it and write it back in */etc/xivo-reporting-db.conf*
* the upgrade is likely to be long if there is a lot of data in *queue_log*. Purge old data out of this table if possible
in order to accelerate the upgrade
* at the end of the upgrade, run *apt-get autoremove* (deletion of xivo-stat, xivo-libdao and xivo-lib-python)
* Check your upgrade through :ref:`check-list`.
* Check that all the services are in the correct version. Compare the output of ``xivocc-dcomp version`` with the table in :ref:`xivosolutions_release`
From version < 1.8
------------------
* XiVO in version < 14.08 is not supported anymore
* if it is required, the upgrade of the XiVO must be done before the upgrade of the pack reporting,
and no call must be performed between the two upgrades
Manual steps for LTS upgrade
============================
From a version using Debian packaging to a version using Docker
---------------------------------------------------------------
See :ref:`upgrade_lts_manual_steps` in XiVO Upgrade page.
* **Beware**: this will require a migration of the original PostgreSQL database to the Dockerised one. For this you need to have free disk space :
the amount of free disk space must equal the size of */var/lib/postgresql*. This check must be performed after docker images have been pulled.
* Run the following commands:
.. code-block:: bash
.. _upgrade_specific_proc_xcc:
apt-get update
service xivo-db-replication stop
service xivo-full-stats stopsource/releasenotes/index.rst
apt-get install pack-reporting xivo-full-stats xivo-reporting-db xivo-db-replication db-utils
service xivo-db-replication stop
service xivo-full-stats stop
Specific procedures
===================
* Install docker, docker-compose and xivocc-installer
* Open `docker-xivocc.yml` and remove sections recording_rsync, config_mgt, recording_server, xuc, xucmgt
* Run `xivocc-dcomp pull`
* CHECK THE FREE DISK SPACE. The next command will migrate the database. This may take several hours.
.. toctree::
:maxdepth: 2
.. code-block:: bash
xivocc_old_pack_reporting_upgrade
sudo -u postgres pg_dump --format c xivo_stats | docker exec -i xivocc_pgxivocc_1 pg_restore -U postgres -d xivo_stats
* Start by `xivocc-dcomp up -d`
From a dockerized version before callbacks
------------------------------------------
Upgrade notes
=============
* Run the following commands:
See :ref:`xivosolutions_release` for version specific informations.