Adding upstream version 1.10.2.upstream/1.10.2upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 230 insertions, 0 deletions

diff --git a/doc/05-Upgrading.md b/doc/05-Upgrading.md
new file mode 100644
index 0000000..63630b6
--- /dev/null
+++ b/doc/05-Upgrading.md
@@ -0,0 +1,230 @@
+<a id="Upgrading"></a>Upgrading
+===============================
+
+Icinga Director is very upgrade-friendly. We never had any complaint referring
+data loss on upgrade. But to be on the safe side, please always [backup](#backup-first)
+your database before running an upgrade.
+
+Then drop the new version to your Icinga Web 2 module folder, and you're all done.
+Eventually refresh the page in your browser<sup>[[1]](#footnote1)</sup>, and you
+are ready to go.
+
+Should there any other actions be required (like [schema migrations](#schema-migrations)),
+you will be told so in your frontend.
+
+Please read more about:
+
+* [Database Backup](#backup-first)
+* [Upgrading to 1.10.x](#upgrade-to-1.10.x)
+* [Upgrading to 1.9.x](#upgrade-to-1.9.x)
+* [Upgrading to 1.8.x](#upgrade-to-1.8.x)
+* [Upgrading to 1.7.x](#upgrade-to-1.7.x)
+* [Upgrading to 1.6.x](#upgrade-to-1.6.x)
+* [Upgrading to 1.5.x](#upgrade-to-1.5.x)
+* [Upgrading to 1.4.x](#upgrade-to-1.4.x)
+* [Upgrading to 1.3.0](#upgrade-to-1.3.0)
+* [Upgrading to 1.2.0](#upgrade-to-1.2.0)
+* [Upgrading to 1.1.0](#upgrade-to-1.1.0)
+* [How to work with the latest GIT master](#git-master)
+* [Database schema upgrades](#schema-migrations)
+* [Job Runner restart](#restart-jobrunner)
+* [Downgrading](#downgrade)
+
+And last but not least, having a look at our [Changelog](82-Changelog.md) is
+usually a good idea before applying an upgrade.
+
+<a name="backup-first"></a>Always take a backup first
+-----------------------------------------------------
+
+All you need for backing up your Director is a snapshot of your database. Please
+use the tools provided by your database backend, like `mysqldump` or `pg_dump`.
+Restoring from a backup is trivial, and Director will always be able to apply
+pending database migrations to an imported old database snapshot.
+
+<a name="upgrade-to-1.9.x"></a>Upgrading to 1.10.x
+--------------------------------------------------
+
+Please check module dependencies, we raised some of them. In case you're missing
+one of them, the Web UI will tell you after the upgrade. You'll then be prompted
+to apply pending Database Migrations.
+
+PHP 7.3 is now claimed to be required, but we still support 5.6+ on Director
+v1.10.x. Same goes for database dependencies: you should upgrade them to recent
+versions, but v1.10 still works on the ones supported with v1.9.x.
+
+<a name="upgrade-to-1.9.x"></a>Upgrading to 1.9.x
+-------------------------------------------------
+
+Please check module dependencies, we raised some of them. In case you're missing
+one of them, the Web UI will tell you after the upgrade. You'll then be prompted
+to apply pending Database Migrations.
+
+<a name="upgrade-to-1.8.x"></a>Upgrading to 1.8.x
+-------------------------------------------------
+
+Before upgrading, please upgrade the [incubator module](https://github.com/Icinga/icingaweb2-module-incubator)
+to (at least) v0.6.0. As always, you'll be prompted to apply pending Database
+Migrations.
+
+<a name="upgrade-to-1.7.x"></a>Upgrading to 1.7.x
+-------------------------------------------------
+
+Since v1.7.0 Icinga Director requires at least PHP 5.6. Also, this version
+introduces new dependencies. Please make sure that the following Icinga Web 2
+modules have been installed and enabled:
+
+* [ipl](https://github.com/Icinga/icingaweb2-module-ipl) (>=0.3.0)
+* [incubator](https://github.com/Icinga/icingaweb2-module-incubator) (>=0.5.0)
+* [reactbundle](https://github.com/Icinga/icingaweb2-module-reactbundle) (>=0.7.0)
+
+Also, the following PHP libraries should be available:
+
+* php-pcntl (might already be built into your PHP binary)
+* php-posix (on RHEL/CentOS this is php-process, or rh-php7x-php-process)
+* php-sockets (might already be built into your PHP binary)
+
+Apart from this, in case you are running 1.6.x or any GIT master since then,
+all you need is to replace the Director module folder with the new one. Or to
+run `git checkout v1.7.x` in case you installed Director from GIT.
+
+As always, you'll then be prompted to apply pending Database Migrations. There
+is now a new, modern (and mandatory) Background Daemon, the old (optional) Jobs
+Daemon must be removed. Please check our [documentation](75-Background-Daemon.md)
+for related instructions.
+
+<a name="upgrade-to-1.6.x"></a>Upgrading to 1.6.x
+-------------------------------------------------
+
+There is nothing special to take care of. In case you are running 1.5.x or any
+GIT master since then, all you need is to replace the Director module folder
+with the new one. Or to run git checkout v1.6.0 in case you installed Director
+from GIT.
+
+As always, you'll then be prompted to apply pending Database Migrations.
+
+<a name="upgrade-to-1.5.x"></a>Upgrading to 1.5.x
+-------------------------------------------------
+
+There is nothing special to take care of. In case you are running 1.4.x or any
+GIT master since then, all you need is to replace the Director module folder
+with the new one. Or to run git checkout v1.5.0 in case you installed Director
+from GIT.
+
+As always, you'll then be prompted to apply pending Database Migrations.
+
+<a name="upgrade-to-1.4.x"></a>Upgrading to 1.4.x
+-------------------------------------------------
+
+Since v1.4.0 Icinga Director requires at least PHP 5.4. Apart from this, there
+is nothing special to take care of. In case you are running 1.3.x or any GIT
+master since then, all you need is to replace the Director module folder with
+the new one. Or to run `git checkout v1.4.x` in case you installed Director
+from GIT.
+
+<a name="upgrade-to-1.3.x"></a>Upgrading to 1.3.x
+-------------------------------------------------
+
+In case you are running 1.2.0 or any GIT master since then, all you need is to
+replace the Director module folder with the new one. Or to run `git checkout v1.3.x`
+in case you installed Director from GIT.
+
+When running Director since 1.1.0 or earlier on PostgreSQL, you might not yet
+have the PostgreSQL crypto extension installed (Package: `postgresql-contrib`) and
+enabled:
+
+     psql -q -c "CREATE EXTENSION pgcrypto;"
+
+
+<a name="upgrade-to-1.2.0"></a>Upgrading to 1.2.0
+-------------------------------------------------
+
+There is nothing special to take care of. In case you are running 1.1.0 or any
+GIT master since then, all you need is to replace the Director module folder with
+the new one. Or to run `git checkout v1.2.0` in case you installed Director from
+GIT.
+
+<a name="upgrade-to-1.1.0"></a>Upgrading to 1.1.0
+-------------------------------------------------
+
+There is nothing special to take care of. In case you are running 1.0.0 or any
+GIT master since then, all you need is to replace the Director module folder with
+the new one. Or to run `git checkout v1.1.0` in case you installed Director from
+GIT.
+
+<a name="git-master"></a>Work with the latest GIT master
+--------------------------------------------------------
+
+Icinga Director is still a very young project. Lots of changes are going on,
+a lot of improvements, bug fixes and new features are still being added every
+month. People living on the bleeding edge might prefer to use all of them as
+soon as possible.
+
+So here is the good news: this is no problem at all. It's absolutely legal and
+encouraged to run Director as a pure GIT clone, installed as such:
+
+```sh
+ICINGAWEB_MODULES=/usr/share/icingaweb2/modules
+DIRECTOR_GIT=https://github.com/Icinga/icingaweb2-module-director.git
+git clone $DIRECTOR_GIT $ICINGAWEB_MODULES/director
+```
+
+Don't worry about schema upgrades. Once they made it into our GIT master there
+will always be a clean upgrade path for you, no manual interaction should ever
+be required. Like every human being, we are not infallible. So, while our strict
+policy says that the master should never break, this might of course happen.
+
+In that case, please [let us know](https://github.com/Icinga/icingaweb2-module-director/issues).
+We'll try to fix your issue as soon as possible.
+
+<a name="schema-migrations"></a>Database schema migrations
+----------------------------------------------------------
+
+In case there are any DB schema upgrades (and that's still often the case) this
+is no problem at all. They will pop up on your Director Dashboard and can be
+applied with a single click. And if your Director is deployed automatically by
+and automation tool like Puppet, also schema upgrades can easily be handled
+that way. Just follow the [related examples](03-Automation.md) in our documentation.
+
+<a name="schema-migrations"></a>Manual schema migrations
+----------------------------------------------------------
+
+Please *do not* manually apply our schema migration files. We are very strict
+about our connection settings, encodings and SQL modes. Client encoding MUST be
+UTF-8, for MySQL and MariaDB we are using the following SQL Mode:
+
+```sql
+SET SESSION SQL_MODE='STRICT_ALL_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,
+ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,ANSI_QUOTES,PIPES_AS_CONCAT,
+NO_ENGINE_SUBSTITUTION';
+```
+
+Our migration files are written based on the assumption that those rules are
+strictly followed, and there may be other ones in future. So please use one
+of the supported migration methods either on the web or on command line and
+stay away from directly interfering with the schema.
+
+<a name="restart-jobrunner"></a>Restart the Job Runner service
+--------------------------------------------------------------
+
+The Job Runner forks it's jobs, so usually a changed code base will take effect
+immediately. However, there might be (schema or code) changes involving the Runner
+process itself. To be on the safe side please always restart it after an upgrade,
+even when it's just a quick `git pull`:
+
+```sh
+systemctl restart director-jobs.service
+```
+
+<a name="downgrade"></a>Downgrading
+-----------------------------------
+
+Downgrading is **not supported**. Most parts of the code will even refuse to
+work in case there are new fields in their database tables. Migrations are
+intentionally provided for upgrades only. In case you want to travel back in
+time please restore a matching former [Database Backup](#backup-first).
+
+<a name="footnote1">[1]</a>:
+Future Icinga Web 2 version will also take care of this step. We want to be
+able to have the latest JavaScript and CSS for any active module to be shipped
+silently without manual interaction to any connected browser within less then
+15 seconds after the latest module has been installed, enabled or upgraded.