Commit f5bb3cc7 authored by Etienne Allovon's avatar Etienne Allovon

Merge branch 'Aldebaran.05' into 2018.05

parents 6fda8bc3 dc5e5fcf
......@@ -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>
......@@ -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
......
.. _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
......
******************
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.
......@@ -260,7 +260,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 +270,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::
......
......@@ -263,7 +263,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).