[pmg-devel] [PATCH pmg-docs 3/3] add upgrade instructions for 5.x to 6.x

[Stoiko Ivanov]

add the documentation as a new appendix, since the information is not directly
documentation for pmg and since there will be a next section with the next
debian release.

Sources are taken from an intial draft in mediawiki, converted with pandoc and
edited manually (quite heavily) to get the markup to render nicely.

Signed-off-by: Stoiko Ivanov <s.ivanov at proxmox.com>
---
 pmg-admin-guide.adoc           |   5 +
 pmg-major-version-upgrade.adoc | 204 +++++++++++++++++++++++++++++++++
 2 files changed, 209 insertions(+)
 create mode 100644 pmg-major-version-upgrade.adoc

diff --git a/pmg-admin-guide.adoc b/pmg-admin-guide.adoc
index 4dfed13..a0bf935 100644
--- a/pmg-admin-guide.adoc
+++ b/pmg-admin-guide.adoc
@@ -199,6 +199,11 @@ include::ldap.conf.adoc[]
 
 :leveloffset: 1
 
+[appendix]
+include::pmg-major-version-upgrade.adoc[]
+
+:leveloffset: 0
+
 [appendix]
 include::GFDL.adoc[]
 
diff --git a/pmg-major-version-upgrade.adoc b/pmg-major-version-upgrade.adoc
new file mode 100644
index 0000000..b34014b
--- /dev/null
+++ b/pmg-major-version-upgrade.adoc
@@ -0,0 +1,204 @@
+[[major_upgrade]]
+Upgrading to new major versions
+===============================
+
+Proxmox Mailgateway 5.x to 6.x
+------------------------------
+Proxmox Mail Gateway 6.x is based on a new major version of Debian.
+Carefully plan the upgrade, *make and verify backups* before beginning,
+and test extensively.
+Depending on the existing configuration, several
+manual steps -- including some downtime -- may be required.
+
+NOTE: A valid and tested backup is _always_ needed before starting the
+upgrade process. Test the backup beforehand in a test lab setup.
+
+In case the system is customized and/or uses additional packages or any
+other third party repositories/packages, ensure those packages are also
+upgraded to and compatible with Debian Buster.
+
+In general, there are two ways to upgrade a Proxmox Mail Gateway 5.x
+system to Proxmox Mail Gateway 6.x:
+
+* A new installation (and restoring the configuration and database from
+the backup)
+* An in-place upgrade via apt (step-by-step)
+
+In both cases emptying the browser cache and reloading the GUI page is
+required after the upgrade.
+
+New Installation
+~~~~~~~~~~~~~~~~
+
+* Install Proxmox Mail Gateway in one of the following three ways:
+** As a xref:pmg_install_on_debian_container[container on top of Debian Buster]
+** xref:pmg_install_on_debian[On top of Debian Buster]
+** By using the xref:pmg_install_iso[ISO image]
+* Restore the backup you have made before the upgrade.
+* Change the IP address and the hostname.
+* Reboot the system.
+* For *clustered setups*:
+** setup the slaves again;
+** then join them to the upgraded master-node (recreate the cluster).
+
+In-place Upgrade
+~~~~~~~~~~~~~~~~
+
+Preconditions
+^^^^^^^^^^^^^
+
+* Upgrade to the latest version of Proxmox Mail Gateway 5.2:
++
+[source,bash]
+----
+apt update
+apt dist-upgrade
+----
+
+* Make a valid and tested backup of Proxmox Mail Gateway:
++
+[source,bash]
+----
+pmgbackup backup
+----
+
+* At least 1GB free disk space at root mount point.
+
+In-place upgrades are done with apt. *Familiarity with apt is required
+to proceed with this upgrade mechanism.*
+
+Actions step-by-step
+^^^^^^^^^^^^^^^^^^^^
+
+* Change the apt sources to Buster - See section
+xref:pmg_package_repositories[Package Repositories]:
++
+[source,bash]
+----
+sed -i 's/stretch/buster/g' /etc/apt/sources.list
+----
++
+Make sure to also edit all files in `/etc/apt/sources.list.d/`
+accordingly. For a Installation from the ISO with the enterprise
+repository the following command will work:
++
+[source,bash]
+----
+echo "deb https://enterprise.proxmox.com/debian/pmg buster pmg-enterprise" > /etc/apt/sources.list.d/pmg-enterprise.list
+----
+
+* Stop postfix and all Proxmox Mail Gateway services (emails will be
+queued by the servers trying to contact the Proxmox Mail Gateway)
++
+This is necessary to prevent changes to the database before the upgrade:
++
+[source,bash]
+----
+systemctl stop postfix pmg-smtp-filter pmgpolicy pmgdaemon pmgproxy pmgmirror pmgtunnel
+----
+
+* Mask postfix and all Proxmox Mailgateway services to prevent them from
+starting during the upgrade:
++
+[source,bash]
+----
+systemctl mask postfix pmg-smtp-filter pmgpolicy pmgdaemon pmgproxy pmgmirror pmgtunnel
+----
+
+* If you have a *cluster*:
+** Stop and mask all cluster-daemons *on all nodes* before you start the
+upgrade of the first node.
++
+[source,bash]
+----
+systemctl stop pmgmirror pmgtunnel
+systemctl mask pmgmirror pmgtunnel
+----
++
+** Then proceed by *upgrading all nodes sequentially*.
+** The service is provided by the nodes not being upgraded.
+
+* Upgrade the system:
++
+[source,bash]
+----
+apt update
+apt dist-upgrade
+----
+
+* Before you upgrade the postgres main cluster, you need to remove the
+automatically created cluster in the new version:
++
+[source,bash]
+----
+pg_dropcluster --stop 11 main
+----
+
+* Upgrade the postgres main cluster from 9.6 to 11 by using `pg_upgradecluster`
+** If possible, use the default setting of dumping the old databases and
+restoring them to avoid problems.
++
+[source,bash]
+----
+pg_upgradecluster -v 11 9.6 main
+----
++
+** If you want to do an in-place upgrade (using `pg_upgrade` instead of
+`pg_dump` and `pg_restore`), you need to `REINDEX` all databases due to
+an incompatibility in glibc:
+*** https://postgresql.verite.pro/blog/2018/08/27/glibc-upgrade.html
+*** https://lists.debian.org/debian-glibc/2019/03/msg00030.html
+*** https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=927129
+
+* Unmask postfix and all non-cluster Proxmox Mail Gateway services to enable
+them again.
++
+[source,bash]
+----
+systemctl unmask postfix pmg-smtp-filter pmgpolicy pmgdaemon pmgproxy
+----
+
+* *Reboot and control the journal* to ensure that everything runs
+correctly.
++
+[source,bash]
+----
+reboot
+journalctl -b
+----
+
+* Remove the old postgres version and its data:
++
+[source,bash]
+----
+apt purge postgresql-9.6 postgresql-client-9.6 postgresql-contrib-9.6
+----
+
+After the Proxmox Mail Gateway upgrade
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* After upgrading, unmask and start all cluster-daemons. This applies to
+upgrades of a single node as well as to upgrades of all nodes in a
+clustered setup:
++
+[source,bash]
+----
+systemctl unmask pmgmirror pmgtunnel
+systemctl start pmgmirror pmgtunnel
+----
+
+Potential issues
+~~~~~~~~~~~~~~~~
+
+* If you've modified the configuration template for postgresql
+(`/var/lib/pmg/templates/postgresql.conf`), make
+sure to compare and update your copy in `/etc/pmg/templates/`
+
+* Clamav-freshclam has a bug with it's AppArmor handling, which seems
+not fixed yet: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=903834
+
+External links
+~~~~~~~~~~~~~~
+
+* https://www.debian.org/releases/buster/amd64/release-notes/[Release
+Notes for Debian 10.0 (buster), 64-bit PC]
-- 
2.20.1