1 # Upgrading Icinga 2 <a id="upgrading-icinga-2"></a>
3 Upgrading Icinga 2 is usually quite straightforward.
4 Ordinarily the only manual steps involved
5 are scheme updates for the IDO database.
7 Specific version upgrades are described below. Please note that version
8 updates are incremental. An upgrade from v2.6 to v2.8 requires to
9 follow the instructions for v2.7 too.
11 ## Upgrading to v2.11 <a id="upgrading-to-2-11"></a>
13 ### Packages <a id="upgrading-to-2-11-packages"></a>
15 EOL distributions where no packages are available with this release:
21 Raspbian Packages are available inside the `icinga-buster` repository
22 on [https://packages.icinga.com](http://packages.icinga.com/raspbian/).
23 Please note that Stretch is not supported suffering from compiler
24 regressions. Upgrade to Raspbian Buster is highly recommended.
26 #### Added: Boost 1.66+
28 The rewrite of our core network stack for cluster and REST API
29 requires newer Boost versions, specifically >= 1.66. For technical
30 details, please continue reading in [this issue](https://github.com/Icinga/icinga2/issues/7041).
32 The package dependencies have been updated for RPM/DEB already.
33 On platforms where EPEL or Backports cannot satisfy this dependency,
34 we provide Boost as package on our [package repository](https://packages.icinga.com):
36 * SLES 12 (this replaces the SDK requirement)
39 * Ubuntu Xenial/Bionic
41 After upgrade, you may remove the old Boost packages (1.53 or anything above)
42 if you don't need them anymore.
44 #### Added: .NET Framework 4.6
46 We modernized the graphical Windows wizard to use the more recent .NET Framework 4.6. This requires that Windows versions
47 older than Windows 10/Windows Server 2016 installs at least [.NET Framework 4.6](https://www.microsoft.com/en-US/download/details.aspx?id=53344). Starting with Windows 10/Windows Server 2016 a .NET Framework 4.6 or higher is installed by default.
49 The MSI-Installer package checks if the .NET Framework 4.6 or higher is present, if not the installation wizard will abort with an error message telling you to install at least .NET Framework 4.6.
53 Our JSON library, namely [YAJL](https://github.com/lloyd/yajl), isn't maintained anymore
54 and may cause [crashes](https://github.com/Icinga/icinga2/issues/6684).
56 It is replaced by [JSON for Modern C++](https://github.com/nlohmann/json) by Niels Lohmann
57 and compiled into the binary as header only include. It helps our way to C++11 and allows
58 to fix additional UTF8 issues more easily. Read more about its [design goals](https://github.com/nlohmann/json#design-goals)
59 and [benchmarks](https://github.com/miloyip/nativejson-benchmark#parsing-time).
61 ### Core <a id="upgrading-to-2-11-core"></a>
63 #### Reload Handling <a id="upgrading-to-2-11-core-reload-handling"></a>
65 2.11 provides fixes for unwanted notifications during restarts.
66 The updated systemd service file now uses the `KillMode=mixed` setting.
68 The reload handling was improved with an umbrella process, which means
69 that normal runtime operations include **3 processes**. You may need to
70 adjust the local instance monitoring of the [procs](08-advanced-topics.md#monitoring-icinga) check.
72 More details can be found in the [technical concepts](19-technical-concepts.md#technical-concepts-core-reload) chapter.
74 #### Downtime Notifications <a id="upgrading-to-2-11-core-downtime-notifications"></a>
76 Imagine that a host/service changes to a HARD NOT-OK state,
77 and its check interval is set to a high interval e.g. 1 hour.
79 A maintenance downtime prevents the notification being sent,
80 but once it ends and the host/service is still in a downtime,
81 no immediate notification is re-sent but you'll have to wait
84 Another scenario is with one-shot notifications (interval=0)
85 which would never notify again after the downtime ends and
86 the problem state being intact. The state change logic requires
87 to recover and become HARD NOT-OK to notify again.
89 In order to solve these problems with filtered/suppressed notifications
90 in downtimes, v2.11 changes the behaviour like this:
92 - If there was a notification suppressed in a downtime, the core stores that information
93 - Once the downtime ends and the problem state is still intact, Icinga checks whether a re-notification should be sent immediately
95 A new cluster message was added to keep this in sync amongst HA masters.
99 > In order to properly use this new feature, all involved endpoints
100 > must be upgraded to v2.11.
102 ### Network Stack <a id="upgrading-to-2-11-network-stack"></a>
104 The core network stack has been rewritten in 2.11 (some say this could be Icinga 3).
106 You can read the full story [here](https://github.com/Icinga/icinga2/issues/7041).
108 The only visible changes for users are:
110 - No more dead-locks with hanging TLS connections (Cluster, REST API)
111 - Better log messages in error cases
112 - More robust and stable with using external libraries instead of self-written socket I/O
114 Coming with this release, we've also updated TLS specific requirements
117 #### TLS 1.2 <a id="upgrading-to-2-11-network-stack-tls-1-2"></a>
119 v2.11 raises the minimum required TLS version to 1.2.
120 This is available since OpenSSL 1.0.1 (EL6 & Debian Jessie).
122 Older Icinga satellites/agents need to support TLS 1.2 during the TLS
125 The `api` feature attribute `tls_protocolmin` now only supports the
126 value `TLSv1.2` being the default.
128 #### Hardened Cipher List <a id="upgrading-to-2-11-network-stack-cipher-list"></a>
130 The previous default cipher list allowed weak ciphers. There's no sane way
131 other than explicitly setting the allowed ciphers.
133 The new default sets this to:
136 ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256
139 You can override this setting in the [api](09-object-types.md#objecttype-apilistener)
140 feature with the `cipher_list` attribute.
142 In case that one of these ciphers is marked as insecure in the future,
143 please let us know with an issue on GitHub.
145 ### Cluster <a id="upgrading-to-2-11-cluster"></a>
147 #### Config Sync <a id="upgrading-to-2-11-cluster-config-sync"></a>
149 2.11 overhauls the cluster config sync in many ways. This includes the
150 following under the hood:
152 - Synced configuration files are not immediately put into production, but left inside a stage.
153 - Unsuccessful config validation never puts the config into production, additional logging and API states are available.
154 - Zone directories which are not configured in zones.conf, are not included anymore on secondary master/satellites/clients.
155 - Synced config change calculation use checksums instead of timestamps to trigger validation/reload. This is more safe, and the usage of timestamps is now deprecated.
156 - Don't allow parallel cluster syncs to avoid race conditions with overridden files.
157 - Deleted directories and files are now purged, previous versions had a bug.
159 Whenever a newer child endpoint receives a configuration update without
160 checksums, it will log a warning.
163 Received configuration update without checksums from parent endpoint satellite1. This behaviour is deprecated. Please upgrade the parent endpoint to 2.11+
166 This is a gentle reminder to upgrade the master and satellites first,
167 prior to installing new clients/agents.
169 Technical details are available in the [technical concepts](19-technical-concepts.md#technical-concepts-cluster-config-sync) chapter.
171 Since the config sync change detection now uses checksums, this may fail
172 with anything else than syncing configuration text files. Syncing binary
173 files were never supported, but rumors say that some users do so.
175 This is now prohibited and logged.
178 [2019-08-02 16:03:19 +0200] critical/ApiListener: Ignoring file '/etc/icinga2/zones.d/global-templates/forbidden.exe' for cluster config sync: Does not contain valid UTF8. Binary files are not supported.
180 (0) Creating config update for file '/etc/icinga2/zones.d/global-templates/forbidden.exe'
181 (1) Activating object 'api' of type 'ApiListener'
184 Such binaries wrapped into JSON-RPC cluster messages may always cause changes
185 and trigger reload loops. In order to prevent such harm in production,
186 use infrastructure tools such as Foreman, Puppet, Ansible, etc. to install
187 plugins on the masters, satellites and agents.
190 #### HA-aware Features <a id="upgrading-to-2-11-cluster-ha-aware-features"></a>
192 v2.11 introduces additional HA functionality similar to the DB IDO feature.
193 This enables the feature being active only on one endpoint while the other
194 endpoint is paused. When one endpoint is shut down, automatic failover happens.
196 This feature is turned off by default keeping the current behaviour. If you need
197 it active on just one endpoint, set `enable_ha = true` on both endpoints in the
198 feature configuration.
200 This affects the following features:
202 * [Elasticsearch](09-object-types.md#objecttype-elasticsearchwriter)
203 * [Gelf](09-object-types.md#objecttype-gelfwriter)
204 * [Graphite](09-object-types.md#objecttype-graphitewriter)
205 * [InfluxDB](09-object-types.md#objecttype-influxdbwriter)
206 * [OpenTsdb](09-object-types.md#objecttype-opentsdbwriter)
207 * [Perfdata](09-object-types.md#objecttype-perfdatawriter) (for PNP)
209 ### HA Failover <a id="upgrading-to-2-11-ha-failover"></a>
211 The reconnect failover has been improved, and the default `failover_timeout`
212 for the DB IDO features has been lowered from 60 to 30 seconds.
213 Object authority updates (required for balancing in the cluster) happen
214 more frequenty (was 30, is 10 seconds).
215 Also the cold startup without object authority updates has been reduced
216 from 60 to 30 seconds. This is to allow cluster reconnects (lowered from 60s to 10s in 2.10)
217 before actually considering a failover/split brain scenario.
219 The [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection) and [IdoPgsqlConnection](09-object-types.md#objecttype-idopgsqlconnection)
220 objects provide a new attribute named `last_failover` which shows the last failover timestamp.
221 This value also is available in the [ido](10-icinga-template-library.md#itl-icinga-ido) CheckCommand output.
224 ### CLI Commands <a id="upgrading-to-2-11-cli-commands"></a>
226 The `troubleshoot` CLI command has been removed. It was never completed,
227 and turned out not to provide required details for GitHub issues anyways.
229 We didn't ask nor endorse users on GitHub/Discourse in the past 2 years, so
230 we're removing it without deprecation.
232 Issue templates, the troubleshooting docs and support knowledge has
235 #### Permissions <a id="upgrading-to-2-11-cli-commands-permissions"></a>
237 CLI commands such as `api setup`, `node wizard/setup`, `feature enable/disable/list`
238 required root permissions previously. Since the file permissions allow
239 the Icinga user to change things already, and users kept asking to
240 run Icinga on their own webspace without root permissions, this is now possible
243 If you are running the commands with a different user than the
244 compiled `ICINGA_USER` and `ICINGA_GROUP` CMake settings (`icinga` everywhere,
245 except Debian with `nagios` for historical reasons), ensure that this
246 user has the capabilities to change to a different user.
248 If you still encounter problems, run the aforementioned CLI commands as root,
251 #### CA List Behaviour Change <a id="upgrading-to-2-11-cli-commands-ca-list"></a>
253 `ca list` only shows the pending certificate signing requests by default.
255 You can use the new `--all` parameter to show all signing requests.
256 Note that Icinga automatically purges signed requests older than 1 week.
258 #### New: CA Remove/Restore <a id="upgrading-to-2-11-cli-commands-ca-remove-restore"></a>
260 `ca remove` allows you to remove pending signing requests. Once the
261 master receives a CSR, and it is marked as removed, the request is
264 `ca restore` allows you to restore a removed signing request. You
265 can list removed signing requests with the new `--removed` parameter
268 ### Configuration <a id="upgrading-to-2-11-configuration"></a>
270 The deprecated `concurrent_checks` attribute in the [checker feature](09-object-types.md#objecttype-checkercomponent)
271 has no effect anymore if set. Please use the [MaxConcurrentChecks](17-language-reference.md#icinga-constants-global-config)
272 constant in [constants.conf](04-configuration.md#constants-conf) instead.
274 ### REST API <a id="upgrading-to-2-11-api"></a>
276 #### Actions <a id="upgrading-to-2-11-api-actions"></a>
278 The [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime-host-all-services)
279 action supports the `all_services` parameter for Host types. Defaults to false.
281 #### Config Packages <a id="upgrading-to-2-11-api-config-packages"></a>
283 Deployed configuration packages require an active stage, with many previous
284 allowed. This mechanism is used by the Icinga Director as external consumer,
285 and Icinga itself for storing runtime created objects inside the `_api`
288 This includes downtimes and comments, which where sometimes stored in the wrong
289 directory path, because the active-stage file was empty/truncated/unreadable at
292 2.11 makes this mechanism more stable and detects broken config packages.
293 It will also attempt to fix them, the following log entry is perfectly fine.
296 [2019-05-10 12:12:09 +0200] information/ConfigObjectUtility: Repairing config package '_api' with stage 'dbe0bef8-c72c-4cc9-9779-da7c4527c5b2'.
299 If you still encounter problems, please follow [this troubleshooting entry](15-troubleshooting.md#troubleshooting-api-missing-runtime-objects).
301 ### DB IDO MySQL Schema <a id="upgrading-to-2-11-db-ido"></a>
303 The schema for MySQL contains an optional update which
304 drops unneeded indexes. You don't necessarily need to apply
307 ### Documentation <a id="upgrading-to-2-11-documentation"></a>
309 * `Custom attributes` have been renamed to `Custom variables` following the name `vars` and their usage in backends and web interfaces.
310 The term `custom attribute` still applies, but referring from the web to the core docs is easier.
311 * The distributed environment term `client` has been refined into `agent`. Wordings and images have been adjusted, and a `client` only is used as
312 general term when requesting something from a parent server role.
313 * The images for basics, modes and scenarios in the distributed monitoring chapter have been re-created from scratch.
314 * `02-getting-started.md` was renamed to `02-installation.md`, `04-configuring-icinga-2.md` into `04-configuration.md`. Apache redirects will be in place.
316 ## Upgrading to v2.10 <a id="upgrading-to-2-10"></a>
318 ### Path Constant Changes <a id="upgrading-to-2-10-path-constant-changes"></a>
320 During package upgrades you may see a notice that the configuration
321 content of features has changed. This is due to a more general approach
322 with path constants in v2.10.
324 The known constants `SysconfDir` and `LocalStateDir` stay intact and won't
326 If you are using these constants in your own custom command definitions
327 or other objects, you are advised to revise them and update them according
328 to the [documentation](17-language-reference.md#icinga-constants).
333 object NotificationCommand "mail-service-notification" {
334 - command = [ SysconfDir + "/icinga2/scripts/mail-service-notification.sh" ]
335 + command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
338 If you have the `ICINGA2_RUN_DIR` environment variable configured in the
339 sysconfig file, you need to rename it to `ICINGA2_INIT_RUN_DIR`. `ICINGA2_STATE_DIR`
340 has been removed and this setting has no effect.
344 > This is important if you rely on the sysconfig configuration in your own scripts.
346 ### New Constants <a id="upgrading-to-2-10-path-new-constants"></a>
348 New [Icinga constants](17-language-reference.md#icinga-constants) have been added in this release.
350 * `Environment` for specifying the Icinga environment. Defaults to not set.
351 * `ApiBindHost` and `ApiBindPort` to allow overriding the default ApiListener values. This will be used for an Icinga addon only.
353 ### Configuration: Namespaces <a id="upgrading-to-2-10-configuration-namespaces"></a>
355 The keywords `namespace` and `using` are now [reserved](17-language-reference.md#reserved-keywords) for the namespace functionality provided
356 with v2.10. Read more about how it works [here](17-language-reference.md#namespaces).
358 ### Configuration: ApiListener <a id="upgrading-to-2-10-configuration-apilistener"></a>
360 Anonymous JSON-RPC connections in the cluster can now be configured with `max_anonymous_clients`
362 The corresponding REST API results from `/v1/status/ApiListener` in `json_rpc` have been renamed
363 from `clients` to `anonymous_clients` to better reflect their purpose. Authenticated clients
364 are counted as connected endpoints. A similar change is there for the performance data metrics.
366 The TLS handshake timeout defaults to 10 seconds since v2.8.2. This can now be configured
367 with the configuration attribute `tls_handshake_timeout`. Beware of performance issues
368 with setting a too high value.
370 ### API: schedule-downtime Action <a id="upgrading-to-2-10-api-schedule-downtime-action"></a>
372 The attribute `child_options` was previously accepting 0,1,2 for specific child downtime settings.
373 This behaviour stays intact, but the new proposed way are specific constants as values (`DowntimeNoChildren`, `DowntimeTriggeredChildren`, `DowntimeNonTriggeredChildren`).
375 ### Notifications: Recovery and Acknowledgement <a id="upgrading-to-2-10-notifications"></a>
377 When a user should be notified on `Problem` and `Acknowledgement`, v2.10 now checks during
378 the `Acknowledgement` notification event whether this user has been notified about a problem before.
381 types = [ Problem, Acknowledgement, Recovery ]
384 If **no** `Problem` notification was sent, and the types filter includes problems for this user,
385 the `Acknowledgement` notification is **not** sent.
387 In contrast to that, the following configuration always sends `Acknowledgement` notifications.
390 types = [ Acknowledgement, Recovery ]
393 This change also restores the old behaviour for `Recovery` notifications. The above configuration
394 leaving out the `Problem` type can be used to only receive recovery notifications. If `Problem`
395 is added to the types again, Icinga 2 checks whether it has notified a user of a problem when
396 sending the recovery notification.
398 More details can be found in [this PR](https://github.com/Icinga/icinga2/pull/6527).
400 ### Stricter configuration validation
402 Some config errors are now fatal. While it never worked before, icinga2 refuses to start now!
404 For example the following started to give a fatal error in 2.10:
408 endpoints = [ "master-server" ]
409 parent = "global-templates"
413 ```critical/config: Error: Zone 'XXX' can not have a global zone as parent.```
415 ### Package Changes <a id="upgrading-to-2-10-package-changes"></a>
417 Debian/Ubuntu drops the `libicinga2` package. `apt-get upgrade icinga2`
418 won't remove such packages leaving the upgrade in an unsatisfied state.
420 Please use `apt-get full-upgrade` or `apt-get dist-upgrade` instead, as explained [here](https://github.com/Icinga/icinga2/issues/6695#issuecomment-430585915).
422 On RHEL/CentOS/Fedora, `icinga2-libs` has been obsoleted. Unfortunately yum's dependency
423 resolver doesn't allow to install older versions than 2.10 then. Please
424 read [here](https://github.com/Icinga/icinga-packaging/issues/114#issuecomment-429264827)
427 RPM packages dropped the [Classic UI](16-upgrading-icinga-2.md#upgrading-to-2-8-removed-classicui-config-package)
428 package in v2.8, Debian/Ubuntu packages were forgotten. This is now the case with this
429 release. Icinga 1.x is EOL by the end of 2018, plan your migration to [Icinga Web 2](https://icinga.com/docs/icingaweb2/latest/).
431 ## Upgrading to v2.9 <a id="upgrading-to-2-9"></a>
433 ### Deprecation and Removal Notes <a id="upgrading-to-2-9-deprecation-removal-notes"></a>
435 - Deprecation of 1.x compatibility features: `StatusDataWriter`, `CompatLogger`, `CheckResultReader`. Their removal is scheduled for 2.11.
436 Icinga 1.x is EOL and will be out of support by the end of 2018.
437 - Removal of Icinga Studio. It always has been experimental and did not satisfy our high quality standards. We've therefore removed it.
439 ### Sysconfig Changes <a id="upgrading-to-2-9-sysconfig-changes"></a>
441 The security fixes in v2.8.2 required moving specific runtime settings
442 into the Sysconfig file and environment. This included that Icinga 2
443 would itself parse this file and read the required variables. This has generated
444 numerous false-positive log messages and led to many support questions. v2.9.0
445 changes this in the standard way to read these variables from the environment, and use
446 sane compile-time defaults.
450 > In order to upgrade, remove everything in the sysconfig file and re-apply
453 There is a bug with existing sysconfig files where path variables are not expanded
454 because systemd [does not support](https://github.com/systemd/systemd/issues/2123)
455 shell variable expansion. This worked with SysVInit though.
457 Edit the sysconfig file and either remove everything, or edit this line
458 on RHEL 7. Modify the path for other distributions.
461 vim /etc/sysconfig/icinga2
463 -ICINGA2_PID_FILE=$ICINGA2_RUN_DIR/icinga2/icinga2.pid
464 +ICINGA2_PID_FILE=/run/icinga2/icinga2.pid
467 If you want to adjust the number of open files for the Icinga application
468 for example, you would just add this setting like this on RHEL 7:
471 vim /etc/sysconfig/icinga2
473 ICINGA2_RLIMIT_FILES=50000
476 Restart Icinga 2 afterwards, the systemd service file automatically puts the
477 value into the application's environment where this is read on startup.
479 ### Setup Wizard Changes <a id="upgrading-to-2-9-setup-wizard-changes"></a>
481 Client and satellite setups previously had the example configuration in `conf.d` included
482 by default. This caused trouble on config sync, or with locally executed checks generating
483 wrong check results for command endpoint clients.
485 In v2.9.0 `node wizard`, `node setup` and the graphical Windows wizard will disable
486 the inclusion by default. You can opt-out and explicitly enable it again if needed.
488 In addition to the default global zones `global-templates` and `director-global`,
489 the setup wizards also offer to specify your own custom global zones and generate
490 the required configuration automatically.
492 The setup wizards also use full qualified names for Zone and Endpoint object generation,
493 either the default values (FQDN for clients) or the user supplied input. This removes
494 the dependency on the `NodeName` and `ZoneName` constant and helps to immediately see
495 the parent-child relationship. Those doing support will also see the benefit in production.
497 ### CLI Command Changes <a id="upgrading-to-2-9-cli-changes"></a>
499 The [node setup](06-distributed-monitoring.md#distributed-monitoring-automation-cli-node-setup)
500 parameter `--master_host` was deprecated and replaced with `--parent_host`.
501 This parameter is now optional to allow connection-less client setups similar to the `node wizard`
502 CLI command. The `parent_zone` parameter has been added to modify the parent zone name e.g.
503 for client-to-satellite setups.
505 The `api user` command which was released in v2.8.2 turned out to cause huge problems with
506 configuration validation, windows restarts and OpenSSL versions. It is therefore removed in 2.9,
507 the `password_hash` attribute for the ApiUser object stays intact but has no effect. This is to ensure
508 that clients don't break on upgrade. We will revise this feature in future development iterations.
510 ### Configuration Changes <a id="upgrading-to-2-9-config-changes"></a>
512 The CORS attributes `access_control_allow_credentials`, `access_control_allow_headers` and
513 `access_control_allow_methods` are now controlled by Icinga 2 and cannot be changed anymore.
515 ### Unique Generated Names <a id="upgrading-to-2-9-unique-name-changes"></a>
517 With the removal of RHEL 5 as supported platform, we can finally use real unique IDs.
518 This is reflected in generating names for e.g. API stage names. Previously it was a handcrafted
519 mix of local FQDN, timestamps and random numbers.
521 ### Custom Vars not updating <a id="upgrading-to-2-9-custom-vars-not-updating"></a>
523 A rare issue preventing the custom vars of objects created prior to 2.9.0 being updated when changed may occur. To
524 remedy this, truncate the customvar tables and restart Icinga 2. The following is an example of how to do this with mysql:
527 $ mysql -uroot -picinga icinga
528 MariaDB [icinga]> truncate icinga_customvariables;
529 Query OK, 0 rows affected (0.05 sec)
530 MariaDB [icinga]> truncate icinga_customvariablestatus;
531 Query OK, 0 rows affected (0.03 sec)
532 MariaDB [icinga]> exit
534 $ sudo systemctl restart icinga2
537 Custom vars should now stay up to date.
540 ## Upgrading to v2.8.2 <a id="upgrading-to-2-8-2"></a>
542 With version 2.8.2 the location of settings formerly found in `/etc/icinga2/init.conf` has changed. They are now
543 located in the sysconfig, `/etc/sysconfig/icinga2` (RPM) or `/etc/default/icinga2` (DPKG) on most systems. The
544 `init.conf` file has been removed and its settings will be ignored. These changes are only relevant if you edited the
545 `init.conf`. Below is a table displaying the new names for the affected settings.
547 Old `init.conf` | New `sysconfig/icinga2`
548 ----------------|------------------------
549 RunAsUser | ICINGA2\_USER
550 RunAsGroup | ICINGA2\_GROUP
551 RLimitFiles | ICINGA2\_RLIMIT\_FILES
552 RLimitProcesses | ICINGA2\_RLIMIT\_PROCESSES
553 RLimitStack | ICINGA2\_RLIMIT\_STACK
555 ## Upgrading to v2.8 <a id="upgrading-to-2-8"></a>
557 ### DB IDO Schema Update to 2.8.0 <a id="upgrading-to-2-8-db-ido"></a>
559 There are additional indexes and schema fixes which require an update.
561 Please proceed here for [MySQL](16-upgrading-icinga-2.md#upgrading-mysql-db) or [PostgreSQL](16-upgrading-icinga-2.md#upgrading-postgresql-db).
565 > `2.8.1.sql` fixes a unique constraint problem with fresh 2.8.0 installations.
566 > You don't need this update if you are upgrading from an older version.
568 ### Changed Certificate Paths <a id="upgrading-to-2-8-certificate-paths"></a>
570 The default certificate path was changed from `/etc/icinga2/pki` to
571 `/var/lib/icinga2/certs`.
574 ---------------------------------------------------|---------------------------------------------------
575 `/etc/icinga2/pki/icinga2-agent1.localdomain.crt` | `/var/lib/icinga2/certs/icinga2-agent1.localdomain.crt`
576 `/etc/icinga2/pki/icinga2-agent1.localdomain.key` | `/var/lib/icinga2/certs/icinga2-agent1.localdomain.key`
577 `/etc/icinga2/pki/ca.crt` | `/var/lib/icinga2/certs/ca.crt`
579 This applies to Windows clients in the same way: `%ProgramData%\etc\icinga2\pki`
580 was moved to `%ProgramData%\var\lib\icinga2\certs`.
583 ----------------------------------------------------------------|----------------------------------------------------------------
584 `%ProgramData%\etc\icinga2\pki\icinga2-agent1.localdomain.crt` | `%ProgramData%\var\lib\icinga2\certs\icinga2-agent1.localdomain.crt`
585 `%ProgramData%\etc\icinga2\pki\icinga2-agent1.localdomain.key` | `%ProgramData%\var\lib\icinga2\certs\icinga2-agent1.localdomain.key`
586 `%ProgramData%\etc\icinga2\pki\ca.crt` | `%ProgramData%\var\lib\icinga2\certs\ca.crt`
591 > The default expected path for client certificates is `/var/lib/icinga2/certs/ + NodeName + {.crt,.key}`.
592 > The `NodeName` constant is usually the FQDN and certificate common name (CN). Check the [conventions](06-distributed-monitoring.md#distributed-monitoring-conventions)
593 > section inside the Distributed Monitoring chapter.
595 The [setup CLI commands](06-distributed-monitoring.md#distributed-monitoring-setup-master) and the
596 default [ApiListener configuration](06-distributed-monitoring.md#distributed-monitoring-apilistener)
597 have been adjusted to these paths too.
599 The [ApiListener](09-object-types.md#objecttype-apilistener) object attributes `cert_path`, `key_path`
600 and `ca_path` have been deprecated and removed from the example configuration.
602 #### Migration Path <a id="upgrading-to-2-8-certificate-paths-migration-path"></a>
606 > Icinga 2 automatically migrates the certificates to the new default location if they
607 > are configured and detected in `/etc/icinga2/pki`.
609 During startup, the migration kicks in and ensures to copy the certificates to the new
610 location. This will also happen if someone updates the certificate files in `/etc/icinga2/pki`
611 to ensure that the new certificate location always has the latest files.
613 This has been implemented in the Icinga 2 binary to ensure it works on both Linux/Unix
614 and the Windows platform.
616 If you are not using the built-in CLI commands and setup wizards to deploy the client certificates,
617 please ensure to update your deployment tools/scripts. This mainly affects
623 * Custom scripts, e.g. Windows Powershell or self-made implementations
625 In order to support a smooth migration between versions older than 2.8 and future releases,
626 the built-in certificate migration path is planned to exist as long as the deprecated
627 `ApiListener` object attributes exist.
629 You are safe to use the existing configuration paths inside the `api` feature.
633 Look at the following example taken from the Director Linux deployment script for clients.
635 * Ensure that the default certificate path is changed from `/etc/icinga2/pki` to `/var/lib/icinga2/certs`.
638 -ICINGA2_SSL_DIR="${ICINGA2_CONF_DIR}/pki"
639 +ICINGA2_SSL_DIR="${ICINGA2_STATE_DIR}/lib/icinga2/certs"
642 * Remove the ApiListener configuration attributes.
645 object ApiListener "api" {
646 - cert_path = SysconfDir + "/icinga2/pki/${ICINGA2_NODENAME}.crt"
647 - key_path = SysconfDir + "/icinga2/pki/${ICINGA2_NODENAME}.key"
648 - ca_path = SysconfDir + "/icinga2/pki/ca.crt"
649 accept_commands = true
654 Test the script with a fresh client installation before putting it into production.
658 > Please support module and script developers in their migration. If you find
659 > any project which would require these changes, create an issue or a patchset in a PR
660 > and help them out. Thanks in advance!
662 ### On-Demand Signing and CA Proxy <a id="upgrading-to-2-8-on-demand-signing-ca-proxy"></a>
664 Icinga 2 v2.8 supports the following features inside the cluster:
666 * Forward signing requests from clients through a satellite instance to a signing master ("CA Proxy").
667 * Signing requests without a ticket. The master instance allows to list and sign CSRs ("On-Demand Signing").
669 In order to use these features, **all instances must be upgraded to v2.8**.
671 More details in [this chapter](06-distributed-monitoring.md#distributed-monitoring-setup-sign-certificates-master).
673 ### Windows Client <a id="upgrading-to-2-8-windows-client"></a>
675 Windows versions older than Windows 10/Server 2016 require the [Universal C Runtime for Windows](https://support.microsoft.com/en-us/help/2999226/update-for-universal-c-runtime-in-windows).
677 ### Removed Bottom Up Client Mode <a id="upgrading-to-2-8-removed-bottom-up-client-mode"></a>
679 This client mode was deprecated in 2.6 and was removed in 2.8.
681 The node CLI command does not provide `list` or `update-config` anymore.
685 > The old migration guide can be found on [GitHub](https://github.com/Icinga/icinga2/blob/v2.7.0/doc/06-distributed-monitoring.md#bottom-up-migration-to-top-down-).
687 The clients don't need to have a local `conf.d` directory included.
689 Icinga 2 continues to run with the generated and imported configuration.
690 You are advised to [migrate](https://github.com/Icinga/icinga2/issues/4798)
691 any existing configuration to the "top down" mode with the help of the
692 Icinga Director or config management tools such as Puppet, Ansible, etc.
695 ### Removed Classic UI Config Package <a id="upgrading-to-2-8-removed-classicui-config-package"></a>
697 The config meta package `classicui-config` and the configuration files
698 have been removed. You need to manually configure
699 this legacy interface. Create a backup of the configuration
700 before upgrading and re-configure it afterwards.
703 ### Flapping Configuration <a id="upgrading-to-2-8-flapping-configuration"></a>
705 Icinga 2 v2.8 implements a new flapping detection algorithm which splits the
706 threshold configuration into low and high settings.
708 `flapping_threshold` is deprecated and does not have any effect when flapping
709 is enabled. Please remove `flapping_threshold` from your configuration. This
710 attribute will be removed in v2.9.
712 Instead you need to use the `flapping_threshold_low` and `flapping_threshold_high`
713 attributes. More details can be found [here](08-advanced-topics.md#check-flapping).
715 ### Deprecated Configuration Attributes <a id="upgrading-to-2-8-deprecated-configuration"></a>
718 --------------|------------------
719 ApiListener | cert\_path (migration happens)
720 ApiListener | key\_path (migration happens)
721 ApiListener | ca\_path (migration happens)
722 Host, Service | flapping\_threshold (has no effect)
724 ## Upgrading to v2.7 <a id="upgrading-to-2-7"></a>
726 v2.7.0 provided new notification scripts and commands. Please ensure to
727 update your configuration accordingly. An advisory has been published [here](https://icinga.com/2017/08/23/advisory-for-icinga-2-v2-7-update-and-mail-notification-scripts/).
729 In case are having troubles with OpenSSL 1.1.0 and the
730 public CA certificates, please read [this advisory](https://icinga.com/2017/08/30/advisory-for-ssl-problems-with-leading-zeros-on-openssl-1-1-0/)
731 and check the [troubleshooting chapter](15-troubleshooting.md#troubleshooting).
733 If Icinga 2 fails to start with an empty reference to `$ICINGA2_CACHE_DIR`
734 ensure to set it inside `/etc/sysconfig/icinga2` (RHEL) or `/etc/default/icinga2` (Debian).
736 RPM packages will put a file called `/etc/sysconfig/icinga2.rpmnew`
737 if you have modified the original file.
742 vim /etc/sysconfig/icinga2
744 ICINGA2_CACHE_DIR=/var/cache/icinga2
746 systemctl restart icinga2
749 ## Upgrading the MySQL database <a id="upgrading-mysql-db"></a>
751 If you want to upgrade an existing Icinga 2 instance, check the
752 `/usr/share/icinga2-ido-mysql/schema/upgrade` directory for incremental schema upgrade file(s).
756 > If there isn't an upgrade file for your current version available, there's nothing to do.
758 Apply all database schema upgrade files incrementally.
761 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/<version>.sql
764 The Icinga 2 DB IDO feature checks the required database schema version on startup
765 and generates an log message if not satisfied.
768 **Example:** You are upgrading Icinga 2 from version `2.4.0` to `2.8.0`. Look into
769 the `upgrade` directory:
772 $ ls /usr/share/icinga2-ido-mysql/schema/upgrade/
773 2.0.2.sql 2.1.0.sql 2.2.0.sql 2.3.0.sql 2.4.0.sql 2.5.0.sql 2.6.0.sql 2.8.0.sql
776 There are two new upgrade files called `2.5.0.sql`, `2.6.0.sql` and `2.8.0.sql`
777 which must be applied incrementally to your IDO database.
780 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.5.0.sql
781 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.6.0.sql
782 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.8.0.sql
785 ## Upgrading the PostgreSQL database <a id="upgrading-postgresql-db"></a>
787 If you want to upgrade an existing Icinga 2 instance, check the
788 `/usr/share/icinga2-ido-pgsql/schema/upgrade` directory for incremental schema upgrade file(s).
792 > If there isn't an upgrade file for your current version available, there's nothing to do.
794 Apply all database schema upgrade files incrementally.
797 # export PGPASSWORD=icinga
798 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/<version>.sql
801 The Icinga 2 DB IDO feature checks the required database schema version on startup
802 and generates an log message if not satisfied.
804 **Example:** You are upgrading Icinga 2 from version `2.4.0` to `2.8.0`. Look into
805 the `upgrade` directory:
808 $ ls /usr/share/icinga2-ido-pgsql/schema/upgrade/
809 2.0.2.sql 2.1.0.sql 2.2.0.sql 2.3.0.sql 2.4.0.sql 2.5.0.sql 2.6.0.sql 2.8.0.sql
812 There are two new upgrade files called `2.5.0.sql`, `2.6.0.sql` and `2.8.0.sql`
813 which must be applied incrementally to your IDO database.
816 # export PGPASSWORD=icinga
817 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.5.0.sql
818 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.6.0.sql
819 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.8.0.sql