]> granicus.if.org Git - icinga2/blob - doc/16-upgrading-icinga-2.md
Merge pull request #6305 from gunnarbeutner/feature/environment-variable
[icinga2] / doc / 16-upgrading-icinga-2.md
1 # Upgrading Icinga 2 <a id="upgrading-icinga-2"></a>
2
3 Upgrading Icinga 2 is usually quite straightforward. Ordinarily the only manual steps involved
4 are scheme updates for the IDO database.
5
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.
9
10 ## Upgrading to v2.9 <a id="upgrading-to-2-9"></a>
11
12 ### Configuration Changes <a id="upgrading-to-2-9-config-changes"></a>
13
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.
16
17 ### CLI Command Changes <a id="upgrading-to-2-9-cli-changes"></a>
18
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.
20
21 ## Upgrading to v2.8.2 <a id="upgrading-to-2-8-2"></a>
22
23 With version 2.8.2 the location of settings formerly found in `/etc/icinga2/init.conf` has changed. They are now
24 located in the sysconfig, `/etc/sysconfig/icinga2` (RPM) or `/etc/default/icinga2` (DPKG) on most systems. The
25 `init.conf` file has been removed and its settings will be ignored. These changes are only relevant if you edited the
26 `init.conf`. Below is a table displaying the new names for the affected settings.
27
28  Old `init.conf` | New `sysconfig/icinga2`
29  ----------------|------------------------
30  RunAsUser       | ICINGA2\_USER
31  RunAsGroup      | ICINGA2\_GROUP
32  RLimitFiles     | ICINGA2\_RLIMIT\_FILES
33  RLimitProcesses | ICINGA2\_RLIMIT\_PROCESSES
34  RLimitStack     | ICINGA2\_RLIMIT\_STACK
35
36 ## Upgrading to v2.8 <a id="upgrading-to-2-8"></a>
37
38 ### DB IDO Schema Update to 2.8.0 <a id="upgrading-to-2-8-db-ido"></a>
39
40 There are additional indexes and schema fixes which require an update.
41
42 Please proceed here for [MySQL](16-upgrading-icinga-2.md#upgrading-mysql-db) or [PostgreSQL](16-upgrading-icinga-2.md#upgrading-postgresql-db).
43
44 > **Note**
45 >
46 > `2.8.1.sql` fixes a unique constraint problem with fresh 2.8.0 installations.
47 > You don't need this update if you are upgrading from an older version.
48
49 ### Changed Certificate Paths <a id="upgrading-to-2-8-certificate-paths"></a>
50
51 The default certificate path was changed from `/etc/icinga2/pki` to
52 `/var/lib/icinga2/certs`.
53
54   Old Path                                           | New Path
55   ---------------------------------------------------|---------------------------------------------------
56   `/etc/icinga2/pki/icinga2-client1.localdomain.crt` | `/var/lib/icinga2/certs/icinga2-client1.localdomain.crt`
57   `/etc/icinga2/pki/icinga2-client1.localdomain.key` | `/var/lib/icinga2/certs/icinga2-client1.localdomain.key`
58   `/etc/icinga2/pki/ca.crt`                          | `/var/lib/icinga2/certs/ca.crt`
59
60 This applies to Windows clients in the same way: `%ProgramData%\etc\icinga2\pki`
61 was moved to `%ProgramData%\var\lib\icinga2\certs`.
62
63   Old Path                                                        | New Path
64   ----------------------------------------------------------------|----------------------------------------------------------------
65   `%ProgramData%\etc\icinga2\pki\icinga2-client1.localdomain.crt` | `%ProgramData%\var\lib\icinga2\certs\icinga2-client1.localdomain.crt`
66   `%ProgramData%\etc\icinga2\pki\icinga2-client1.localdomain.key` | `%ProgramData%\var\lib\icinga2\certs\icinga2-client1.localdomain.key`
67   `%ProgramData%\etc\icinga2\pki\ca.crt`                          | `%ProgramData%\var\lib\icinga2\certs\ca.crt`
68
69
70 > **Note**
71 >
72 > The default expected path for client certificates is `/var/lib/icinga2/certs/ + NodeName + {.crt,.key}`.
73 > The `NodeName` constant is usually the FQDN and certificate common name (CN). Check the [conventions](06-distributed-monitoring.md#distributed-monitoring-conventions)
74 > section inside the Distributed Monitoring chapter.
75
76 The [setup CLI commands](06-distributed-monitoring.md#distributed-monitoring-setup-master) and the
77 default [ApiListener configuration](06-distributed-monitoring.md#distributed-monitoring-apilistener)
78 have been adjusted to these paths too.
79
80 The [ApiListener](09-object-types.md#objecttype-apilistener) object attributes `cert_path`, `key_path`
81 and `ca_path` have been deprecated and removed from the example configuration.
82
83 #### Migration Path <a id="upgrading-to-2-8-certificate-paths-migration-path"></a>
84
85 > **Note**
86 >
87 > Icinga 2 automatically migrates the certificates to the new default location if they
88 > are configured and detected in `/etc/icinga2/pki`.
89
90 During startup, the migration kicks in and ensures to copy the certificates to the new
91 location. This will also happen if someone updates the certificate files in `/etc/icinga2/pki`
92 to ensure that the new certificate location always has the latest files.
93
94 This has been implemented in the Icinga 2 binary to ensure it works on both Linux/Unix
95 and the Windows platform.
96
97 If you are not using the built-in CLI commands and setup wizards to deploy the client certificates,
98 please ensure to update your deployment tools/scripts. This mainly affects
99
100 * Puppet modules
101 * Ansible playbooks
102 * Chef cookbooks
103 * Salt recipes
104 * Custom scripts, e.g. Windows Powershell or self-made implementations
105
106 In order to support a smooth migration between versions older than 2.8 and future releases,
107 the built-in certificate migration path is planned to exist as long as the deprecated
108 `ApiListener` object attributes exist.
109
110 You are safe to use the existing configuration paths inside the `api` feature.
111
112 **Example**
113
114 Look at the following example taken from the Director Linux deployment script for clients.
115
116 * Ensure that the default certificate path is changed from `/etc/icinga2/pki` to `/var/lib/icinga2/certs`.
117
118 ```
119 -ICINGA2_SSL_DIR="${ICINGA2_CONF_DIR}/pki"
120 +ICINGA2_SSL_DIR="${ICINGA2_STATE_DIR}/lib/icinga2/certs"
121 ```
122
123 * Remove the ApiListener configuration attributes.
124
125 ```
126 object ApiListener "api" {
127 -  cert_path = SysconfDir + "/icinga2/pki/${ICINGA2_NODENAME}.crt"
128 -  key_path = SysconfDir + "/icinga2/pki/${ICINGA2_NODENAME}.key"
129 -  ca_path = SysconfDir + "/icinga2/pki/ca.crt"
130   accept_commands = true
131   accept_config = true
132 }
133 ```
134
135 Test the script with a fresh client installation before putting it into production.
136
137 > **Tip**
138 >
139 > Please support module and script developers in their migration. If you find
140 > any project which would require these changes, create an issue or a patchset in a PR
141 > and help them out. Thanks in advance!
142
143 ### On-Demand Signing and CA Proxy <a id="upgrading-to-2-8-on-demand-signing-ca-proxy"></a>
144
145 Icinga 2 v2.8 supports the following features inside the cluster:
146
147 * Forward signing requests from clients through a satellite instance to a signing master ("CA Proxy").
148 * Signing requests without a ticket. The master instance allows to list and sign CSRs ("On-Demand Signing").
149
150 In order to use these features, **all instances must be upgraded to v2.8**.
151
152 More details in [this chapter](06-distributed-monitoring.md#distributed-monitoring-setup-sign-certificates-master).
153
154 ### Windows Client <a id="upgrading-to-2-8-windows-client"></a>
155
156 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).
157
158 ### Removed Bottom Up Client Mode <a id="upgrading-to-2-8-removed-bottom-up-client-mode"></a>
159
160 This client mode was deprecated in 2.6 and was removed in 2.8.
161
162 The node CLI command does not provide `list` or `update-config` anymore.
163
164 > **Note**
165 >
166 > 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-).
167
168 The clients don't need to have a local `conf.d` directory included.
169
170 Icinga 2 continues to run with the generated and imported configuration.
171 You are advised to [migrate](https://github.com/Icinga/icinga2/issues/4798)
172 any existing configuration to the "top down" mode with the help of the
173 Icinga Director or config management tools such as Puppet, Ansible, etc.
174
175
176 ### Removed Classic UI Config Package <a id="upgrading-to-2-8-removed-classicui-config-package"></a>
177
178 The config meta package `classicui-config` and the configuration files
179 have been removed. You need to manually configure
180 this legacy interface. Create a backup of the configuration
181 before upgrading and re-configure it afterwards.
182
183
184 ### Flapping Configuration <a id="upgrading-to-2-8-flapping-configuration"></a>
185
186 Icinga 2 v2.8 implements a new flapping detection algorithm which splits the
187 threshold configuration into low and high settings.
188
189 `flapping_threshold` is deprecated and does not have any effect when flapping
190 is enabled. Please remove `flapping_threshold` from your configuration. This
191 attribute will be removed in v2.9.
192
193 Instead you need to use the `flapping_threshold_low` and `flapping_threshold_high`
194 attributes. More details can be found [here](08-advanced-topics.md#check-flapping).
195
196 ### Deprecated Configuration Attributes <a id="upgrading-to-2-8-deprecated-configuration"></a>
197
198   Object        | Attribute
199   --------------|------------------
200   ApiListener   | cert\_path (migration happens)
201   ApiListener   | key\_path (migration happens)
202   ApiListener   | ca\_path (migration happens)
203   Host, Service | flapping\_threshold (has no effect)
204
205 ## Upgrading to v2.7 <a id="upgrading-to-2-7"></a>
206
207 v2.7.0 provided new notification scripts and commands. Please ensure to
208 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/).
209
210 In case are having troubles with OpenSSL 1.1.0 and the
211 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/)
212 and check the [troubleshooting chapter](15-troubleshooting.md#troubleshooting).
213
214 If Icinga 2 fails to start with an empty reference to `$ICINGA2_CACHE_DIR`
215 ensure to set it inside `/etc/sysconfig/icinga2` (RHEL) or `/etc/default/icinga2` (Debian).
216
217 RPM packages will put a file called `/etc/sysconfig/icinga2.rpmnew`
218 if you have modified the original file.
219
220 Example on CentOS 7:
221
222 ```
223 vim /etc/sysconfig/icinga2
224
225 ICINGA2_CACHE_DIR=/var/cache/icinga2
226
227 systemctl restart icinga2
228 ```
229
230 ## Upgrading the MySQL database <a id="upgrading-mysql-db"></a>
231
232 If you want to upgrade an existing Icinga 2 instance, check the
233 `/usr/share/icinga2-ido-mysql/schema/upgrade` directory for incremental schema upgrade file(s).
234
235 > **Note**
236 >
237 > If there isn't an upgrade file for your current version available, there's nothing to do.
238
239 Apply all database schema upgrade files incrementally.
240
241 ```
242 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/<version>.sql
243 ```
244
245 The Icinga 2 DB IDO feature checks the required database schema version on startup
246 and generates an log message if not satisfied.
247
248
249 **Example:** You are upgrading Icinga 2 from version `2.4.0` to `2.8.0`. Look into
250 the `upgrade` directory:
251
252 ```
253 $ ls /usr/share/icinga2-ido-mysql/schema/upgrade/
254 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
255 ```
256
257 There are two new upgrade files called `2.5.0.sql`, `2.6.0.sql` and `2.8.0.sql`
258 which must be applied incrementally to your IDO database.
259
260 ```
261 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.5.0.sql
262 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.6.0.sql
263 # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/upgrade/2.8.0.sql
264 ```
265
266 ## Upgrading the PostgreSQL database <a id="upgrading-postgresql-db"></a>
267
268 If you want to upgrade an existing Icinga 2 instance, check the
269 `/usr/share/icinga2-ido-pgsql/schema/upgrade` directory for incremental schema upgrade file(s).
270
271 > **Note**
272 >
273 > If there isn't an upgrade file for your current version available, there's nothing to do.
274
275 Apply all database schema upgrade files incrementally.
276
277 ```
278 # export PGPASSWORD=icinga
279 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/<version>.sql
280 ```
281
282 The Icinga 2 DB IDO feature checks the required database schema version on startup
283 and generates an log message if not satisfied.
284
285 **Example:** You are upgrading Icinga 2 from version `2.4.0` to `2.8.0`. Look into
286 the `upgrade` directory:
287
288 ```
289 $ ls /usr/share/icinga2-ido-pgsql/schema/upgrade/
290 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
291 ```
292
293 There are two new upgrade files called `2.5.0.sql`, `2.6.0.sql` and `2.8.0.sql`
294 which must be applied incrementally to your IDO database.
295
296 ```
297 # export PGPASSWORD=icinga
298 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.5.0.sql
299 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.6.0.sql
300 # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/upgrade/2.8.0.sql
301 ```