Commit a749d5da authored by Etienne Allovon's avatar Etienne Allovon

Refactor and calrify the upgrade pages for XiVO PBX and XiVO CC

The work consist mainly of :
- harmonizing upgrade procedure for XiVO CC and XiVO PBX
- having a smaller upgrade page for XiVO PBX which will be clearer
- distinguish specific upgrade proc from version proc issue
parent 955a7acf
.. _xivosolutions_release:
****************************
XiVO Solutions Release notes
XiVO Solutions Release Notes
****************************
2017.01
......
.. _upgrading-a-cluster:
*******************
Upgrading a cluster
*******************
Here are the steps for upgrading a cluster, i.e. two XiVO with :ref:`high-availability`:
#. On the master : deactivate the database replication by commenting the cron in
:file:`/etc/cron.d/xivo-ha-master`
#. On the slave, deactivate the xivo-check-master-status script cronjob by commenting the line in
:file:`/etc/cron.d/xivo-ha-slave`
#. On the slave, start the upgrade::
xivo-slave:~$ xivo-upgrade
#. When the slave has finished, start the upgrade on the master::
xivo-master:~$ xivo-upgrade
#. When done, launch the database replication manually::
xivo-master:~$ xivo-master-slave-db-replication <slave ip>
#. Reactivate the cronjobs (see steps 1 and 2)
.. _other_version_proc:
*********************************
Other Version Specific Procedures
*********************************
Several version specific procedure are listed here.
Upgrading from XiVO 14.11 and before
====================================
When upgrading from XiVO 14.11 or earlier, you must do the following, before the normal upgrade::
sed -i 's/xivo\.fr/xivo.solutions/g' /etc/apt/sources.list.d/*.list
Upgrading from XiVO 14.01, 14.02, 14.03, 14.04 installed from the ISO
=====================================================================
In those versions, xivo-upgrade keeps XiVO on the same version. You must do the following, before
the normal upgrade::
echo "deb http://mirror.xivo.solutions/debian/ xivo-five main" > /etc/apt/sources.list.d/xivo-upgrade.list \
&& apt-get update \
&& apt-get install xivo-fai \
&& rm /etc/apt/sources.list.d/xivo-upgrade.list \
&& apt-get update
Upgrading from XiVO 13.24 and before
====================================
When upgrading from XiVO 13.24 or earlier, you must do the following, before the normal upgrade:
#. Ensure that the file :file:`/etc/apt/sources.list` is *not* configured on ``archive.debian.org``.
Instead, it must be configured with a non-archive mirror, but still on the ``squeeze``
distribution, even if it is not present on this mirror. For example::
deb http://ftp.us.debian.org/debian squeeze main
#. Add ``archive.debian.org`` in another file::
cat > /etc/apt/sources.list.d/squeeze-archive.list <<EOF
deb http://archive.debian.org/debian/ squeeze main
EOF
And after the upgrade::
rm /etc/apt/sources.list.d/squeeze-archive.list
Upgrading from XiVO 13.03 and before
====================================
When upgrading from XiVO 13.03 or earlier, you must do the following, before the normal upgrade::
wget http://mirror.xivo.solutions/xivo_current.key -O - | apt-key add -
Upgrading from XiVO 12.13 and before
====================================
When upgrading from XiVO 12.13 or earlier, you must do the following, before the normal upgrade::
apt-get update
apt-get install debian-archive-keyring
Upgrading from XiVO 1.2.1 and before
====================================
Upgrading from 1.2.0 or 1.2.1 requires a special procedure before executing ``xivo-upgrade``::
apt-get update
apt-get install xivo-upgrade
/usr/bin/xivo-upgrade
.. _switch-to-xivo.solutions:
************************
Switch to xivo.solutions
************************
.. note:: If you are in *XiVO PBX* **below 2016.03** you should first switch to xivo.solutions mirrors.
In order to do that follow the following procedure:
#. Download the ``switch-to-xivo-solutions`` script::
wget http://mirror.xivo.solutions/debian/tools/migration-tools/switch-to-xivo-solutions.sh
chmod +x ./switch-to-xivo-solutions.sh
#. Execute the script::
./switch-to-xivo-solutions.sh
...
Your XiVO has been switched to xivo.solutions successfully.
Votre XiVO a été basculé vers xivo.solutions avec succès.
#. Update the sources list::
apt-get update
......@@ -4,191 +4,144 @@
Upgrading
*********
Upgrading a XiVO is done by executing commands through a terminal on the
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.
To upgrade your XiVO to the latest version, you **must** use the ``xivo-upgrade`` script. You can
start an upgrade with the command::
xivo-upgrade
Overview
========
.. note::
* You can't use xivo-upgrade if you have not run the wizard yet
* Upgrading from a version prior to XiVO 1.2 is not supported.
* When upgrading XiVO, you **must** also upgrade **all** associated XiVO
Clients. There is currently no retro-compatibility on older XiVO Client
versions.
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:
This script will update XiVO and restart all services.
* the system (Debian packages)
* and the *XiVO PBX* packages
There are 2 options you can pass to xivo-upgrade:
* ``-d`` to only download packages without installing them. **This will still upgrade the package containing xivo-upgrade and xivo-service**.
* ``-f`` to force upgrade, without asking for user confirmation
.. warning:: The following applies to *XiVO PBX* **>= 2016.03**. For older version, see :ref:`version_specific_upgrade` section.
``xivo-upgrade`` uses the following environment variables:
There are three cases:
* ``XIVO_CONFD_PORT`` to set the port used to query the :ref:`HTTP API of xivo-confd <confd-api>`
(default is 9486)
#. :ref:`Upgrade to the latest XiVO PBX version <upgrade_latest_version_xpbx>`,
#. :ref:`Upgrade to a specific XiVO PBX version <upgrade_specific_version_xpbx>` (or archive version),
#. :ref:`Upgrade to the latest subversion <upgrade_latest_subversion_xpbx>` of your current installed version.
Upgrade procedure
=================
.. _upgrade_latest_version_xpbx:
* Read all existing Upgrade Notes (see below) starting from your version to the latest version.
* For custom setups, follow the required procedures described below (e.g. HA cluster).
* To download the packages beforehand, run ``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.
* When ready, run ``xivo-upgrade`` which will start the upgrade process. **Telephony services will
be stopped during the process**
* 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 to **latest** version
-----------------------------
To upgrade to the latest version, you have to update the sources list to point to *xivo-five*. You have to do it with the command ``xivo-dist`` supplied in *XiVO PBX*::
.. _version_specific_upgrade:
xivo-dist xivo-five
Version-specific upgrade procedures
===================================
Switch to xivo.solutions
------------------------
.. _upgrade_specific_version_xpbx:
To follow Avencall's official releases you must switch to xivo.solutions mirrors.
In order to do that follow the following procedure:
Upgrade to **specific** version
-------------------------------
#. Download the ``switch-to-xivo-solutions`` script::
To upgrade to a **specific** 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 **2016.04**::
wget http://mirror.xivo.solutions/debian/tools/migration-tools/switch-to-xivo-solutions.sh
chmod +x ./switch-to-xivo-solutions.sh
xivo-dist xivo-2016.04-latest
#. Execute the script::
./switch-to-xivo-solutions.sh
.. _upgrade_latest_subversion_xpbx:
...
Upgrade to latest **subversion**
--------------------------------
Your XiVO has been switched to xivo.solutions successfully.
Votre XiVO a été basculé vers xivo.solutions avec succès.
When you are already in a *specific* version (e.g. 2016.04), you may want to upgrade to the **latest subversion** of this release (e.g. 2016.04.03) to benefit of the latest *fixes* shipped in this version. You have to do it with the ``xivo-dist`` command. For example, if you want to upgrade to the latest subversion of 2016.04 version::
#. Update the sources list::
xivo-dist xivo-2016.04-latest
apt-get update
Preparing the upgrade
=====================
Upgrading from XiVO 14.11 and before
------------------------------------
To prepare the upgrade you should:
When upgrading from XiVO 14.11 or earlier, you must do the following, before the normal upgrade::
#. Read :ref:`xivosolutions_release` starting from your 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.
sed -i 's/xivo\.fr/xivo.solutions/g' /etc/apt/sources.list.d/*.list
Upgrade
=======
Upgrading from XiVO 14.01, 14.02, 14.03, 14.04 installed from the ISO
---------------------------------------------------------------------
#. 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**::
In those versions, xivo-upgrade keeps XiVO on the same version. You must do the following, before
the normal upgrade::
xivo-upgrade
echo "deb http://mirror.xivo.solutions/debian/ xivo-five main" > /etc/apt/sources.list.d/xivo-upgrade.list \
&& apt-get update \
&& apt-get install xivo-fai \
&& rm /etc/apt/sources.list.d/xivo-upgrade.list \
&& apt-get update
#. 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.
Upgrading from XiVO 13.24 and before
------------------------------------
.. _upgrade_specific_proc:
When upgrading from XiVO 13.24 or earlier, you must do the following, before the normal upgrade:
#. Ensure that the file :file:`/etc/apt/sources.list` is *not* configured on ``archive.debian.org``.
Instead, it must be configured with a non-archive mirror, but still on the ``squeeze``
distribution, even if it is not present on this mirror. For example::
deb http://ftp.us.debian.org/debian squeeze main
Specific procedures
===================
#. Add ``archive.debian.org`` in another file::
.. toctree::
:maxdepth: 1
cat > /etc/apt/sources.list.d/squeeze-archive.list <<EOF
deb http://archive.debian.org/debian/ squeeze main
EOF
cluster
migrate_i386_to_amd64
And after the upgrade::
rm /etc/apt/sources.list.d/squeeze-archive.list
.. _version_specific_upgrade:
Version-specific upgrade procedures
===================================
Upgrading from XiVO 13.03 and before
------------------------------------
.. note:: If your *XiVO PBX* is **below 2016.03** you have first to :ref:`switch-to-xivo.solutions` mirrors.
When upgrading from XiVO 13.03 or earlier, you must do the following, before the normal upgrade::
.. toctree::
:maxdepth: 2
wget http://mirror.xivo.solutions/xivo_current.key -O - | apt-key add -
switch_xivosolutions
other_version_specific
Upgrading from XiVO 12.13 and before
Upgrading to/from an archive version
------------------------------------
When upgrading from XiVO 12.13 or earlier, you must do the following, before the normal upgrade::
apt-get update
apt-get install debian-archive-keyring
Upgrading from XiVO 1.2.1 and before
------------------------------------
.. toctree::
:maxdepth: 1
Upgrading from 1.2.0 or 1.2.1 requires a special procedure before executing ``xivo-upgrade``::
archives
apt-get update
apt-get install xivo-upgrade
/usr/bin/xivo-upgrade
.. _upgrading-a-cluster:
.. _xivo-upgrade_script:
Upgrading a cluster
xivo-upgrade script
===================
Here are the steps for upgrading a cluster, i.e. two XiVO with :ref:`high-availability`:
#. On the master : deactivate the database replication by commenting the cron in
:file:`/etc/cron.d/xivo-ha-master`
#. On the slave, deactivate the xivo-check-master-status script cronjob by commenting the line in
:file:`/etc/cron.d/xivo-ha-slave`
#. On the slave, start the upgrade::
xivo-slave:~$ xivo-upgrade
#. When the slave has finished, start the upgrade on the master::
xivo-master:~$ xivo-upgrade
#. When done, launch the database replication manually::
xivo-master:~$ xivo-master-slave-db-replication <slave ip>
#. Reactivate the cronjobs (see steps 1 and 2)
Upgrading to/from an archive version
====================================
.. toctree::
:maxdepth: 1
.. note::
* You can't use xivo-upgrade if you have not run the wizard yet
* Upgrading from a version prior to *XiVO PBX* 1.2 is not supported.
* When upgrading XiVO, you **must** also upgrade **all** associated XiVO
Clients. There is currently no retro-compatibility on older *XiVO PBX* Client
versions.
archives
This script will update *XiVO PBX* and restart all services.
There are 2 options you can pass to xivo-upgrade:
Upgrading from i386 (32 bits) to amd64 (64 bits)
================================================
* ``-d`` to only download packages without installing them. **This will still upgrade the package containing xivo-upgrade and xivo-service**.
* ``-f`` to force upgrade, without asking for user confirmation
.. toctree::
:maxdepth: 1
``xivo-upgrade`` uses the following environment variables:
migrate_i386_to_amd64
* ``XIVO_CONFD_PORT`` to set the port used to query the :ref:`HTTP API of xivo-confd <confd-api>`
(default is 9486)
Troubleshooting
......
......@@ -12,28 +12,31 @@ The following components will be upgraded :
.. warning:: This upgrade procedure applies only to XiVO CC installed via the ``xivocc-installer`` package.
Prerequisites
=============
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-solutions.list`.
There are three cases:
#. Upgrade to the **latest** *XiVO CC* version,
#. Upgrade to **a specific** version (or an archive version),
#. Upgrade to **the latest subversion** of your current installed version.
#. :ref:`Upgrade to the latest XiVO CC version <upgrade_latest_version_xcc>`,
#. :ref:`Upgrade to a specific version <upgrade_specific_version_xcc>` (or archive version),
#. :ref:`Upgrade to the latest subversion <upgrade_latest_subversion_xcc>` of your current installed version.
.. _upgrade_latest_version_xcc:
1. Upgrade to *latest* version
------------------------------
Upgrade to **latest** version
-----------------------------
To upgrade to the latest version the sources list must point towards *debian* URI and *xivo-solutions* suite::
deb http://mirror.xivo.solutions/debian/ xivo-solutions main
2. Upgrade to **specific** version
-----------------------------------
.. _upgrade_specific_version_xcc:
Upgrade to **specific** version
-------------------------------
To upgrade to a **specific** version the sources list must point towards *archive* URI and *xivo-solutions-VERSION* suite.
......@@ -46,8 +49,8 @@ Note the ``/archive/`` and ``-2016.04`` above.
.. _upgrade_latest_subversion_xcc:
3. Upgrade to latest **subversion**
-----------------------------------
Upgrade to latest **subversion**
--------------------------------
After the release of a *version* (e.g. *2016.04*) we may backport some bugfixes in this version.
We will then create a **subversion** (e.g. 2016.04 **.01**) shipping these bugfixes.
......@@ -69,6 +72,14 @@ To upgrade to the **latest subversion** of your current installed *version* you
#. And upgrade the containers with ``dcomp up -d`` command.
Preparing the upgrade
=====================
To prepare the upgrade you should:
#. Read :ref:`xivosolutions_release` starting from your version to the version you target.
Upgrade
=======
......@@ -80,7 +91,15 @@ When you have checked the sources.list you can upgrade with the following comman
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 run the new version by *dcomp up -d* eventually preceded by the *dcomp pull* to download the new images.
Then you have to:
#. Download the new images::
dcomp pull
#. And run the new container (**All XiVO CC services will be restarted**)::
dcomp up -d
Upgrade notes
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment