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