1 # Upgrading Icinga 2 <a id="upgrading-icinga-2"></a>
3 Upgrading Icinga 2 is usually quite straightforward. Ordinarily the only manual steps involved
4 are scheme updates for the IDO database.
6 Specific version upgrades are described below. Please note that version
7 updates are incremental. An upgrade from v2.6 to v2.8 requires to
8 follow the instructions for v2.7 too.
10 ## Upgrading to v2.9 <a id="upgrading-to-2-9"></a>
12 ### Configuration Changes <a id="upgrading-to-2-9-config-changes"></a>
14 The CORS attributes `access_control_allow_credentials`, `access_control_allow_headers` and
15 `access_control_allow_methods` are now controlled by Icinga 2 and cannot be changed anymore.
17 ### CLI Command Changes <a id="upgrading-to-2-9-cli-changes"></a>
19 The `node setup` parameter `--master_host` was deprecated and replaced with `--parent_host`. This parameter is now optional to allow connection-less client setups similar to the `node wizard` CLI command. The `parent_zone` parameter has been added to modify the parent zone name e.g. for client-to-satellite setups.
21 The `api user` command which was released in v2.8.2 turned out to cause huge problems with
22 configuration validation, windows restarts and OpenSSL versions. It is therefore removed in 2.9,
23 the `password_hash` attribute for the ApiUser object stays intact but has no effect. This is to ensure
24 that clients don't break on upgrade. We will revise this feature in future development iterations.
26 ## Upgrading to v2.8.2 <a id="upgrading-to-2-8-2"></a>
28 With version 2.8.2 the location of settings formerly found in `/etc/icinga2/init.conf` has changed. They are now
29 located in the sysconfig, `/etc/sysconfig/icinga2` (RPM) or `/etc/default/icinga2` (DPKG) on most systems. The
30 `init.conf` file has been removed and its settings will be ignored. These changes are only relevant if you edited the
31 `init.conf`. Below is a table displaying the new names for the affected settings.
33 Old `init.conf` | New `sysconfig/icinga2`
34 ----------------|------------------------
35 RunAsUser | ICINGA2\_USER
36 RunAsGroup | ICINGA2\_GROUP
37 RLimitFiles | ICINGA2\_RLIMIT\_FILES
38 RLimitProcesses | ICINGA2\_RLIMIT\_PROCESSES
39 RLimitStack | ICINGA2\_RLIMIT\_STACK
41 ## Upgrading to v2.8 <a id="upgrading-to-2-8"></a>
43 ### DB IDO Schema Update to 2.8.0 <a id="upgrading-to-2-8-db-ido"></a>
45 There are additional indexes and schema fixes which require an update.
47 Please proceed here for [MySQL](16-upgrading-icinga-2.md#upgrading-mysql-db) or [PostgreSQL](16-upgrading-icinga-2.md#upgrading-postgresql-db).
51 > `2.8.1.sql` fixes a unique constraint problem with fresh 2.8.0 installations.
52 > You don't need this update if you are upgrading from an older version.
54 ### Changed Certificate Paths <a id="upgrading-to-2-8-certificate-paths"></a>
56 The default certificate path was changed from `/etc/icinga2/pki` to
57 `/var/lib/icinga2/certs`.
60 ---------------------------------------------------|---------------------------------------------------
61 `/etc/icinga2/pki/icinga2-client1.localdomain.crt` | `/var/lib/icinga2/certs/icinga2-client1.localdomain.crt`
62 `/etc/icinga2/pki/icinga2-client1.localdomain.key` | `/var/lib/icinga2/certs/icinga2-client1.localdomain.key`
63 `/etc/icinga2/pki/ca.crt` | `/var/lib/icinga2/certs/ca.crt`
65 This applies to Windows clients in the same way: `%ProgramData%\etc\icinga2\pki`
66 was moved to `%ProgramData%\var\lib\icinga2\certs`.
69 ----------------------------------------------------------------|----------------------------------------------------------------
70 `%ProgramData%\etc\icinga2\pki\icinga2-client1.localdomain.crt` | `%ProgramData%\var\lib\icinga2\certs\icinga2-client1.localdomain.crt`
71 `%ProgramData%\etc\icinga2\pki\icinga2-client1.localdomain.key` | `%ProgramData%\var\lib\icinga2\certs\icinga2-client1.localdomain.key`
72 `%ProgramData%\etc\icinga2\pki\ca.crt` | `%ProgramData%\var\lib\icinga2\certs\ca.crt`
77 > The default expected path for client certificates is `/var/lib/icinga2/certs/ + NodeName + {.crt,.key}`.
78 > The `NodeName` constant is usually the FQDN and certificate common name (CN). Check the [conventions](06-distributed-monitoring.md#distributed-monitoring-conventions)
79 > section inside the Distributed Monitoring chapter.
81 The [setup CLI commands](06-distributed-monitoring.md#distributed-monitoring-setup-master) and the
82 default [ApiListener configuration](06-distributed-monitoring.md#distributed-monitoring-apilistener)
83 have been adjusted to these paths too.
85 The [ApiListener](09-object-types.md#objecttype-apilistener) object attributes `cert_path`, `key_path`
86 and `ca_path` have been deprecated and removed from the example configuration.
88 #### Migration Path <a id="upgrading-to-2-8-certificate-paths-migration-path"></a>
92 > Icinga 2 automatically migrates the certificates to the new default location if they
93 > are configured and detected in `/etc/icinga2/pki`.
95 During startup, the migration kicks in and ensures to copy the certificates to the new
96 location. This will also happen if someone updates the certificate files in `/etc/icinga2/pki`
97 to ensure that the new certificate location always has the latest files.
99 This has been implemented in the Icinga 2 binary to ensure it works on both Linux/Unix
100 and the Windows platform.
102 If you are not using the built-in CLI commands and setup wizards to deploy the client certificates,
103 please ensure to update your deployment tools/scripts. This mainly affects
109 * Custom scripts, e.g. Windows Powershell or self-made implementations
111 In order to support a smooth migration between versions older than 2.8 and future releases,
112 the built-in certificate migration path is planned to exist as long as the deprecated
113 `ApiListener` object attributes exist.
115 You are safe to use the existing configuration paths inside the `api` feature.
119 Look at the following example taken from the Director Linux deployment script for clients.
121 * Ensure that the default certificate path is changed from `/etc/icinga2/pki` to `/var/lib/icinga2/certs`.
124 -ICINGA2_SSL_DIR="${ICINGA2_CONF_DIR}/pki"
125 +ICINGA2_SSL_DIR="${ICINGA2_STATE_DIR}/lib/icinga2/certs"
128 * Remove the ApiListener configuration attributes.
131 object ApiListener "api" {
132 - cert_path = SysconfDir + "/icinga2/pki/${ICINGA2_NODENAME}.crt"
133 - key_path = SysconfDir + "/icinga2/pki/${ICINGA2_NODENAME}.key"
134 - ca_path = SysconfDir + "/icinga2/pki/ca.crt"
135 accept_commands = true
140 Test the script with a fresh client installation before putting it into production.
144 > Please support module and script developers in their migration. If you find
145 > any project which would require these changes, create an issue or a patchset in a PR
146 > and help them out. Thanks in advance!
148 ### On-Demand Signing and CA Proxy <a id="upgrading-to-2-8-on-demand-signing-ca-proxy"></a>
150 Icinga 2 v2.8 supports the following features inside the cluster:
152 * Forward signing requests from clients through a satellite instance to a signing master ("CA Proxy").
153 * Signing requests without a ticket. The master instance allows to list and sign CSRs ("On-Demand Signing").
155 In order to use these features, **all instances must be upgraded to v2.8**.
157 More details in [this chapter](06-distributed-monitoring.md#distributed-monitoring-setup-sign-certificates-master).
159 ### Windows Client <a id="upgrading-to-2-8-windows-client"></a>
161 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).
163 ### Removed Bottom Up Client Mode <a id="upgrading-to-2-8-removed-bottom-up-client-mode"></a>
165 This client mode was deprecated in 2.6 and was removed in 2.8.
167 The node CLI command does not provide `list` or `update-config` anymore.
171 > 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-).
173 The clients don't need to have a local `conf.d` directory included.
175 Icinga 2 continues to run with the generated and imported configuration.
176 You are advised to [migrate](https://github.com/Icinga/icinga2/issues/4798)
177 any existing configuration to the "top down" mode with the help of the
178 Icinga Director or config management tools such as Puppet, Ansible, etc.
181 ### Removed Classic UI Config Package <a id="upgrading-to-2-8-removed-classicui-config-package"></a>
183 The config meta package `classicui-config` and the configuration files
184 have been removed. You need to manually configure
185 this legacy interface. Create a backup of the configuration
186 before upgrading and re-configure it afterwards.
189 ### Flapping Configuration <a id="upgrading-to-2-8-flapping-configuration"></a>
191 Icinga 2 v2.8 implements a new flapping detection algorithm which splits the
192 threshold configuration into low and high settings.
194 `flapping_threshold` is deprecated and does not have any effect when flapping
195 is enabled. Please remove `flapping_threshold` from your configuration. This
196 attribute will be removed in v2.9.
198 Instead you need to use the `flapping_threshold_low` and `flapping_threshold_high`
199 attributes. More details can be found [here](08-advanced-topics.md#check-flapping).
201 ### Deprecated Configuration Attributes <a id="upgrading-to-2-8-deprecated-configuration"></a>
204 --------------|------------------
205 ApiListener | cert\_path (migration happens)
206 ApiListener | key\_path (migration happens)
207 ApiListener | ca\_path (migration happens)
208 Host, Service | flapping\_threshold (has no effect)
210 ## Upgrading to v2.7 <a id="upgrading-to-2-7"></a>
212 v2.7.0 provided new notification scripts and commands. Please ensure to
213 update your configuration accordingly. An advisory has been published [here](https://www.icinga.com/2017/08/23/advisory-for-icinga-2-v2-7-update-and-mail-notification-scripts/).
215 In case are having troubles with OpenSSL 1.1.0 and the
216 public CA certificates, please read [this advisory](https://www.icinga.com/2017/08/30/advisory-for-ssl-problems-with-leading-zeros-on-openssl-1-1-0/)
217 and check the [troubleshooting chapter](15-troubleshooting.md#troubleshooting).
219 If Icinga 2 fails to start with an empty reference to `$ICINGA2_CACHE_DIR`
220 ensure to set it inside `/etc/sysconfig/icinga2` (RHEL) or `/etc/default/icinga2` (Debian).
222 RPM packages will put a file called `/etc/sysconfig/icinga2.rpmnew`
223 if you have modified the original file.
228 vim /etc/sysconfig/icinga2
230 ICINGA2_CACHE_DIR=/var/cache/icinga2
232 systemctl restart icinga2
235 ## Upgrading the MySQL database <a id="upgrading-mysql-db"></a>
237 If you want to upgrade an existing Icinga 2 instance, check the
238 `/usr/share/icinga2-ido-mysql/schema/upgrade` directory for incremental schema upgrade file(s).
242 > If there isn't an upgrade file for your current version available, there's nothing to do.
244 Apply all database schema upgrade files incrementally.
247 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/<version>.sql
250 The Icinga 2 DB IDO feature checks the required database schema version on startup
251 and generates an log message if not satisfied.
254 **Example:** You are upgrading Icinga 2 from version `2.4.0` to `2.8.0`. Look into
255 the `upgrade` directory:
258 $ ls /usr/share/icinga2-ido-mysql/schema/upgrade/
259 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
262 There are two new upgrade files called `2.5.0.sql`, `2.6.0.sql` and `2.8.0.sql`
263 which must be applied incrementally to your IDO database.
266 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.5.0.sql
267 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.6.0.sql
268 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.8.0.sql
271 ## Upgrading the PostgreSQL database <a id="upgrading-postgresql-db"></a>
273 If you want to upgrade an existing Icinga 2 instance, check the
274 `/usr/share/icinga2-ido-pgsql/schema/upgrade` directory for incremental schema upgrade file(s).
278 > If there isn't an upgrade file for your current version available, there's nothing to do.
280 Apply all database schema upgrade files incrementally.
283 # export PGPASSWORD=icinga
284 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/<version>.sql
287 The Icinga 2 DB IDO feature checks the required database schema version on startup
288 and generates an log message if not satisfied.
290 **Example:** You are upgrading Icinga 2 from version `2.4.0` to `2.8.0`. Look into
291 the `upgrade` directory:
294 $ ls /usr/share/icinga2-ido-pgsql/schema/upgrade/
295 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
298 There are two new upgrade files called `2.5.0.sql`, `2.6.0.sql` and `2.8.0.sql`
299 which must be applied incrementally to your IDO database.
302 # export PGPASSWORD=icinga
303 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.5.0.sql
304 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.6.0.sql
305 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.8.0.sql