Adding upstream version 2.12.1.upstream/2.12.1upstream

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

1 files changed, 435 insertions, 0 deletions

diff --git a/doc/80-Upgrading.md b/doc/80-Upgrading.md
new file mode 100644
index 0000000..c6f4b7b
--- /dev/null
+++ b/doc/80-Upgrading.md
@@ -0,0 +1,435 @@
+# Upgrading Icinga Web 2 <a id="upgrading"></a>
+
+Specific version upgrades are described below. Please note that upgrades are incremental. An upgrade from
+v2.6 to v2.8 requires to follow the instructions for v2.7 too.
+
+## Upgrading to Icinga Web 2.12.0
+
+**Database Schema**
+
+With the latest Icinga Web versions, you no longer need to manually import sql upgrade scripts. Icinga Web `>= 2.12`
+offers you the possibility to perform such migrations in an easy way. You can find and apply all pending migrations
+of your Icinga Web environment in the menu at `System -> Migrations`.
+
+You can still apply the `2.12.0.sql` upgrade script manually, depending on your database vendor.
+For package installations you can find this file in `/usr/share/icingaweb2/schema/*-upgrades/`.
+
+## Upgrading to Icinga Web 2.11.x
+
+**General**
+
+* Support for Internet Explorer 11 has been removed.
+* The Vagrant file and all its assets have been removed.
+
+**Database Schema**
+
+* Please apply the `v2.11.0.sql` upgrade script depending on your database vendor.
+  As of version `2.11.4`, upgrade scripts can be found at `/usr/share/icingaweb2/schema/*-upgrades/`.
+  Older versions install these files to `/usr/share/doc/icingaweb2/schema/*-upgrades/` for RPM-based systems 
+  and `/usr/share/icingaweb2/etc/schema/*-upgrades/` for Debian or Ubuntu.
+
+**Breaking changes**
+
+* The `user:local_name` macro in restrictions has been removed. Use `user.local_name` now.
+* User preferences stored in INI files are not loaded anymore. Migrate yours with
+  `icingacli migrate preferences` before the upgrade, if you haven't already.
+
+**Framework changes affecting third-party code**
+
+* When loading library CSS assets, CSS files and LESS files are handled differently now. Only the latter
+  is parsed as LESS.
+* jQuery is not bundled anymore as it's now part of the library icinga-php-thirdparty v0.11.0. It's shipped there
+  in version 3.6.0. (Previously bundled was jQuery 3.4.1)
+* All the following classes have been removed:
+  * `Icinga\User\Preferences\Store\IniStore`: Preferences in INI files are not supported anymore.
+  * `Icinga\User\Preferences\Store\DbStore`: Its methods have been added to the `PreferencesStore` class.
+  * `Icinga\Util\String`: Use `Icinga\Util\StringHelper` instead.
+  * `Icinga\Util\Translator`: Use `\ipl\I18n\StaticTranslator::$instance` or `\ipl\I18n\Translation` instead.
+  * `Icinga\Module\Migrate\Clicommands\DashboardCommand`: Deleted without substitution.
+  * `Icinga\Web\Hook\TicketHook`: Use `Icinga\Application\Hook\TicketHook` instead.
+  * `Icinga\Web\Hook\GrapherHook`: Use `Icinga\Application\Hook\GrapherHook` instead.
+  * `Icinga\Module\Monitoring\Environment`: Not in use.
+  * `Icinga\Module\Monitoring\Backend`: Use `Icinga\Module\Monitoring\Backend\MonitoringBackend` instead.
+* All the following methods have been removed:
+  * `loader.js.addUrlFlag()`: Use `Icinga.Utils.addUrlFlag()` instead.
+  * `Url::setBaseUrl()`: Please create a new url from scratch instead.
+  * `Url::getBaseUrl()`: Use either `Url::getBasePath()` or `Url::getAbsoluteUrl()` now.
+  * `ApplicationBootstrap::setupZendAutoloader()`: Since it does nothing, all usages removed.
+  * `ApplicationBootstrap::listLocales()`: Use `\ipl\I18n\GettextTranslator::listLocales()` instead.
+  * `Module::registerHook()`: Use `provideHook()` instead.
+  * `Web::getMenu()`: Instantiate the menu class `new Menu()` directly instead.
+  * `AesCrypt::encryptToBase64()`: Use `AesCrypt::encrypt()` instead as it also returns a base64 encoded string.
+  * `AesCrypt::decryptFromBase64()`: Use `AesCrypt::decrypt()` instead as it also returns a base64 decoded string.
+  * `InlinePie::disableNoScript()`: Empty method.
+  * `SimpleQuery::paginate()`: Use `Icinga\Web\Controller::setupPaginationControl()` and/or `Icinga\Web\Widget\Paginator` instead.
+  * `LdapConnection::connect()`: The connection is established lazily since .. a long time.
+  * `MonitoredObject::matches()`: Use `$filter->matches($object)` instead.
+  * `MonitoredObject::fromParams()`: Deleted without substitution.
+  * `DataView::fromRequest()`: Use `$backend->select()->from($viewName)` instead.
+  * `DataView::sort()`: Use `DataView::order()` instead.
+  * `MonitoringBackend::createBackend()`: Use `MonitoringBackend::instance()` instead.
+  * `DbConnection::getConnection()`: Use `Connection::getDbAdapter()` instead.
+  * `DbQuery::renderFilter()`: Use `DbConnection::renderFilter()` instead.
+  * `DbQuery::whereToSql()`: Use `DbConnection::renderFilter()` instead.
+
+## Upgrading to Icinga Web 2 2.10.x
+
+**General**
+
+* The theme "solarized-dark" has been removed due to the introduction of the new default dark mode.
+
+**Deprecations**
+
+* Builtin support for PDF exports using the `dompdf` library will be dropped with version 2.12.
+  It is highly recommended to use [Icinga PDF Export](https://github.com/Icinga/icingaweb2-module-pdfexport)
+  instead.
+
+**Discontinued package updates**
+
+* We will stop offering major updates for Debian 9 (Stretch) starting with version 2.11.
+  However, versions 2.9 and 2.10 will continue to receive minor updates on this platform.
+
+[icinga.com](https://icinga.com/subscription/support-details/) provides an overview about
+currently supported distributions.
+
+**Framework changes affecting third-party code**
+
+* Asset support for modules (#3961) introduced with v2.8 has now been removed.
+* `expandable-toggle`-support has been removed. Use `class="collapsible" data-visible-height=0`
+  to achieve the same effect. (Available since v2.7.0)
+* The `.var()` LESS mixin and the LESS function `extract-variable-default` have been removed (introduced with v2.9)
+
+## Upgrading to Icinga Web 2 2.9.1
+
+**Database Schema**
+
+* Please apply the `v2.9.1.sql` upgrade script depending on your database vendor.
+  In package installations this file can be found in `/usr/share/doc/icingaweb2/schema/*-upgrades/`
+  (Debian/Ubuntu: `/usr/share/icingaweb2/etc/schema/*-upgrades/`).
+
+## Upgrading to Icinga Web 2 2.9.x
+
+**Installation**
+
+* Icinga Web 2 now requires the [Icinga PHP Library (ipl)](https://github.com/Icinga/icinga-php-library) (>= 0.6)
+  and [Icinga PHP Thirdparty](https://github.com/Icinga/icinga-php-thirdparty) (>= 0.10). Please make sure to
+  install both when upgrading. We provide packages for them and if you've installed Icinga Web 2 already by
+  package they should be installed automatically during the upgrade.
+* [Icinga Business Process Modelling](https://github.com/Icinga/icingaweb2-module-businessprocess/releases/tag/v2.3.1)
+  has been updated to v2.3.1. If you're using this module, this version is required when upgrading.
+
+**General**
+
+* For database connections to the IDO running on MySQL, a default charset (`latin1`) is now applied.
+  If you had previously problems with special characters and umlauts and you've set this charset
+  already manually, no change is required. However, if your IDO resource configuration has another
+  charset configured than this, it is highly recommended to clear this setting. Otherwise the default
+  won't apply and characters may still be shown incorrectly in the UI.
+
+**Database Schema**
+
+* Icinga Web 2 now permits its users to stay logged in. This requires a new database table.
+  * Please apply the `v2.9.0.sql` upgrade script depending on your database vendor.
+    In package installations this file can be found in `/usr/share/doc/icingaweb2/schema/*-upgrades/`
+    (Debian/Ubuntu: `/usr/share/icingaweb2/etc/schema/*-upgrades/`).
+
+**Breaking changes**
+
+* Password changes are not allowed by default anymore
+  * The fake refusal `no-user/password-change` has now been changed to a grant `user/password-change`.
+    Any user that had `no-user/password-change` previously still cannot change passwords. Though any
+    user that didn't have this *permission*, needs to be granted `user/password-change` now in order
+    to change passwords.
+
+**Deprecations**
+
+* Support for EOL PHP versions (5.6, 7.0, 7.1 and 7.2) will be removed with version 2.11
+* Support for Internet Explorer will be completely removed with version 2.11
+  * New features after v2.9 will already not (necessarily) be available in Internet Explorer
+* `user.local_name` replaces the `user:local_name` macro in restrictions, and the latter will be removed with
+  version 2.11
+* The configuration backend type `INI` is not configurable anymore. **A database is now mandatory.**
+  * Existing configurations using this configuration backend type will stop working with the
+    release of v2.11.
+  * To migrate your local user preferences to database, enable the `migrate` module and use the command
+    `icingacli migrate preferences`. If you already setup the configuration database, it will work right
+    away. If not, pass it the resource you'd like to use as configuration database with `--resource=`.
+  * Note that this only applies to user preferences. Other configurations are still stored
+    in `.ini` files. (#3770)
+* The Vagrant file and all its assets will be removed with version 2.11
+
+**Framework changes affecting third-party code**
+
+* The `jquery-migrate` compatibility layer for Javascript code working with jQuery 2.x has been removed.
+  It has been introduced with v2.7 when we upgraded jQuery to v3.4.1 in order to allow module developers
+  a seamless upgrade chance. If a module still has UI glitches after an upgrade to v2.9, please contact
+  the module developer.
+* The method `getHtmlForEvent` of the `EventDetailsExtensionHook` previously received the host or service
+  object of an event. Now the actual event object is passed to it instead.
+* Asset support for modules (#3961) introduced with v2.8 has now been deprecated in favor of library
+  support (#4272) and will be removed with v2.10. We don't expect broad usage of this feature since
+  it's been introduced with the latest major version, so it's already being removed with the next one.
+
+## Upgrading to Icinga Web 2 2.8.x
+
+**Changes in packaging and dependencies**
+
+Valid for distributions:
+
+* RHEL / CentOS 7
+  * Upgrade to PHP 7.3 via RedHat SCL
+
+After upgrading to version 2.8.0 you'll get the new `rh-php73` dependency installed. This is a drop-in replacement
+for the previous `rh-php71` dependency and only requires the setup of a new fpm service and possibly some copying
+of customized configurations.
+
+**php.ini or php-fpm settings** you have tuned in the past need to be copied over to the new path:
+
+From `/etc/opt/rh/rh-php71/` to `/etc/opt/rh/rh-php73/`.
+
+Don't forget to also install any additional **php-modules** for PHP 7.3 you've had previously installed
+for e.g. Icinga Web 2 modules.
+
+There's also a new **service** included which replaces the previous one for php-fpm:
+
+Stop the old service: `systemctl stop rh-php71-php-fpm.service`  
+Start the new service: `systemctl start rh-php73-php-fpm.service`
+
+You can now safely remove the previous dependency if you like:
+
+`yum remove rh-php71*`
+
+**Discontinued package updates**
+
+Icinga Web 2 v2.8+ is not supported on these platforms:
+
+* RHEL / CentOS 6
+* Debian 8 Jessie
+* Ubuntu 16.04 LTS (Xenial Xerus)
+
+Please consider an upgrade of your central Icinga system to a newer distribution release.
+
+[icinga.com](https://icinga.com/subscription/support-details/) provides an overview about
+currently supported distributions.
+
+**Framework changes affecting third-party code**
+
+* Url parameter `view=compact` is now deprecated. `showCompact` should be used instead.
+  Details are in pull request [#4164](https://github.com/Icinga/icingaweb2/pull/4164).
+* Form elements of type checkbox now need to be checked prior submission if they're
+  required. Previously setting `required => true` didn't cause the browser to complain
+  if such a checkbox wasn't checked. Browsers now do complain if so.
+* The general layout now uses flexbox instead of fixed positioning. This applies to the
+  `#header`, `#sidebar`, `#main`, `#footer`, `#col1`, `#col2` and a column's controls.
+  `#sidebar` and `#main` are now additionally wrapped in a new container `#content-wrapper`.
+
+## Upgrading to Icinga Web 2 2.7.x <a id="upgrading-to-2.7.x"></a>
+
+**Breaking changes**
+
+* We've upgraded jQuery to version 3.4.1. If you're a module developer, please add `?_dev` to your address bar to check
+  for log messages emitted by jquery-migrate. (https://github.com/jquery/jquery-migrate) Your javascript code will still
+  work, though jquery-migrate will notify you if you're utilizing deprecated/removed functions. jquery-migrate will be
+  removed with Icinga Web v2.8 and code not adjusted accordingly will stop working.
+* If you're using a language other than english and you've adjusted or disabled module dashboards, you'll need to
+  update all of your `dashboard.ini` files. A CLI command exists to assist you with this task. Enable the `migrate`
+  module and run the following on the host where these files exist: `icingacli migrate dashboard sections --verbose`
+
+## Upgrading to Icinga Web 2 2.6.x <a id="upgrading-to-2.6.x"></a>
+
+* Icinga Web 2 version 2.6.x does not introduce any backward incompatible change.
+
+## Upgrading to Icinga Web 2 2.5.x <a id="upgrading-to-2.5.x"></a>
+
+> **Attention**
+>
+> Icinga Web 2 v2.5 requires **at least PHP 5.6**.
+
+**Breaking changes**
+
+* Hash marks (`#`) in INI files are no longer recognized as comments by
+  [parse_ini_file](https://secure.php.net/manual/en/function.parse-ini-file.php) since PHP 7.0.
+* Existing sessions of logged-in users do no longer work as expected due to a change in the `User` data structure.
+  Everyone who was logged in before the upgrade has to log out once.
+
+**Changes in packaging and dependencies**
+
+Valid for distributions:
+
+* RHEL / CentOS 6 + 7
+  * Upgrading to PHP 7.0 / 7.1 via RedHat SCL (new dependency)
+  * See [Upgrading to FPM](02-Installation.md#upgrading-to-fpm) for manual steps that
+    are required
+* SUSE SLE 12
+  * Upgrading PHP to >= 5.6.0 via the alternative packages.
+    You might have to confirm the replacement of PHP < 5.6 - but that
+    should work with any other PHP app as well.
+  * Make sure to enable the new Apache module `a2enmod php7` and restart `apache2`
+
+**Discontinued package updates**
+
+Icinga Web 2 v2.5+ is not supported on these platforms:
+
+* Debian 7 wheezy
+* Ubuntu 14.04 LTS (trusty)
+* SUSE SLE 11 (all service packs)
+
+Please consider an upgrade of your central Icinga system to a newer distribution release.
+
+[packages.icinga.com](https://packages.icinga.com) provides an overview about currently supported distributions.
+
+**Database schema**
+
+Icinga Web 2 v2.5.0 requires a schema update for the database. The database schema has been adjusted to support
+usernames up to 254 characters. This is necessary to support the new domain-aware authentication feature.
+
+Continue here for [MySQL](80-Upgrading.md#upgrading-mysql-db) and [PostgreSQL](80-Upgrading.md#upgrading-pgsql-db).
+
+## Upgrading to Icinga Web 2 2.4.x <a id="upgrading-to-2.4.x"></a>
+
+* Icinga Web 2 version 2.4.x does not introduce any backward incompatible change.
+
+## Upgrading to Icinga Web 2 2.3.x <a id="upgrading-to-2.3.x"></a>
+
+* Icinga Web 2 version 2.3.x does not introduce any backward incompatible change.
+
+## Upgrading to Icinga Web 2 2.2.0 <a id="upgrading-to-2.2.0"></a>
+
+* The menu entry `Authorization` beneath `Config` has been renamed to `Authentication`. The role, user backend and user
+  group backend configuration which was previously found beneath `Authentication` has been moved to `Application`.
+  
+## Upgrading to Icinga Web 2 2.1.x <a id="upgrading-to-2.1.x"></a>
+
+* Since Icinga Web 2 version 2.1.3 LDAP user group backends respect the configuration option `group_filter`.
+  Users who changed the configuration manually and used the option `filter` instead
+  have to change it back to `group_filter`.
+
+## Upgrading to Icinga Web 2 2.0.0 <a id="upgrading-to-2.0.0"></a>
+
+* Icinga Web 2 installations from package on RHEL/CentOS 7 now depend on `php-ZendFramework` which is available through
+  the [EPEL repository](https://fedoraproject.org/wiki/EPEL). Before, Zend was installed as Icinga Web 2 vendor library
+  through the package `icingaweb2-vendor-zend`. After upgrading, please make sure to remove the package
+  `icingaweb2-vendor-zend`.
+
+* Icinga Web 2 version 2.0.0 requires permissions for accessing modules. Those permissions are automatically generated
+  for each installed module in the format `module/<moduleName>`. Administrators have to grant the module permissions to
+  users and/or user groups in the roles configuration for permitting access to specific modules.
+  In addition, restrictions provided by modules are now configurable for each installed module too. Before,
+  a module had to be enabled before having the possibility to configure restrictions.
+
+* The **instances.ini** configuration file provided by the monitoring module
+  has been renamed to **commandtransports.ini**. The content and location of
+  the file remains unchanged.
+
+* The location of a user's preferences has been changed from
+  **&lt;config-dir&gt;/preferences/&lt;username&gt;.ini** to
+  **&lt;config-dir&gt;/preferences/&lt;username&gt;/config.ini**.
+  The content of the file remains unchanged.
+
+## Upgrading to Icinga Web 2 Release Candidate 1 <a id="upgrading-to-rc1"></a>
+
+The first release candidate of Icinga Web 2 introduces the following non-backward compatible changes:
+
+* The database schema has been adjusted and the tables `icingaweb_group` and
+  `icingaweb_group_membership` were altered to ensure referential integrity.
+  Please use the upgrade script located in **etc/schema/** to update your
+  database schema
+
+* Users who are using PostgreSQL < v9.1 are required to upgrade their
+  environment to v9.1+ as this is the new minimum required version
+  for utilizing PostgreSQL as database backend
+
+* The restrictions `monitoring/hosts/filter` and `monitoring/services/filter`
+  provided by the monitoring module were merged together. The new
+  restriction is called `monitoring/filter/objects` and supports only a
+  predefined subset of filter columns. Please see the module's security
+  related documentation for more details.
+
+## Upgrading to Icinga Web 2 Beta 3 <a id="upgrading-to-beta3"></a>
+
+Because Icinga Web 2 Beta 3 does not introduce any backward incompatible change you don't have to change your
+configuration files after upgrading to Icinga Web 2 Beta 3.
+
+## Upgrading to Icinga Web 2 Beta 2 <a id="upgrading-to-beta2"></a>
+
+Icinga Web 2 Beta 2 introduces access control based on roles for secured actions. If you've already set up Icinga Web 2,
+you are required to create the file **roles.ini** beneath Icinga Web 2's configuration directory with the following
+content:
+```
+[administrators]
+users = "your_user_name, another_user_name"
+permissions = "*"
+```
+
+After please log out from Icinga Web 2 and log in again for having all permissions granted.
+
+If you delegated authentication to your web server using the `autologin` backend, you have to switch to the `external`
+authentication backend to be able to log in again. The new name better reflects 
+what's going on. A similar change
+affects environments that opted for not storing preferences, your new backend is `none`.
+
+## Upgrading the MySQL Database <a id="upgrading-mysql-db"></a>
+
+If you installed Icinga Web 2 from package, please check the upgrade scripts located in
+**/usr/share/doc/icingaweb2/schema/mysql-upgrades** (Debian/Ubuntu: **/usr/share/icingaweb2/etc/schema/mysql-upgrades**)
+to update your database schema.
+In case you installed Icinga Web 2 from source, please find the upgrade scripts in **etc/schema/mysql-upgrades**.
+
+> **Note**
+>
+> If there isn't an upgrade file for your current version available, there's nothing to do.
+
+Apply all database schema upgrade files incrementally.
+
+```
+# mysql -u root -p icingaweb2 < /usr/share/doc/icingaweb2/schema/mysql-upgrades/<version>.sql
+```
+
+**Example:** You are upgrading Icinga Web 2 from version `2.4.0` to `2.5.0`. Look into
+the `upgrade` directory:
+
+```
+$ ls /usr/share/doc/icingaweb2/schema/mysql-upgrades/
+2.0.0beta3-2.0.0rc1.sql  2.5.0.sql
+```
+
+The upgrade file `2.5.0.sql` must be applied for the v2.5.0 release. If there are multiple
+upgrade files involved, apply them incrementally.
+
+```
+# mysql -u root -p icinga < /usr/share/doc/icingaweb2/schema/mysql-upgrades/2.5.0.sql
+```
+
+## Upgrading the PostgreSQL Database <a id="upgrading-pgsql-db"></a>
+
+If you installed Icinga Web 2 from package, please check the upgrade scripts located in
+**/usr/share/doc/icingaweb2/schema/pgsql-upgrades** (Debian/Ubuntu: **/usr/share/icingaweb2/etc/schema/pgsql-upgrades**)
+to update your database schema.
+In case you installed Icinga Web 2 from source, please find the upgrade scripts in **etc/schema/pgsql-upgrades**.
+
+> **Note**
+>
+> If there isn't an upgrade file for your current version available, there's nothing to do.
+
+Apply all database schema upgrade files incrementally.
+
+```
+# export PGPASSWORD=icingaweb2
+# psql -U icingaweb2 -d icingaweb2 < /usr/share/doc/icingaweb2/schema/pgsql-upgrades/<version>.sql
+```
+
+**Example:** You are upgrading Icinga Web 2 from version `2.4.0` to `2.5.0`. Look into
+the `upgrade` directory:
+
+```
+$ ls /usr/share/doc/icingaweb2/schema/pgsql-upgrades/
+2.0.0beta3-2.0.0rc1.sql  2.5.0.sql
+```
+
+The upgrade file `2.5.0.sql` must be applied for the v2.5.0 release. If there are multiple
+upgrade files involved, apply them incrementally.
+
+```
+# export PGPASSWORD=icingaweb2
+# psql -U icingaweb2 -d icingaweb2 < /usr/share/doc/icingaweb2/schema/pgsql-upgrades/2.5.0.sql
+```