diff options
Diffstat (limited to 'doc/80-Upgrading.md')
| -rw-r--r-- | doc/80-Upgrading.md | 435 |
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 + **<config-dir>/preferences/<username>.ini** to + **<config-dir>/preferences/<username>/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 +``` |