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