granicus.if.org Git - icinga2/blob - doc/17-troubleshooting.md

   1 # <a id="troubleshooting"></a> Icinga 2 Troubleshooting
   2
   3 ## <a id="troubleshooting-information-required"></a> Which information is required
   4
   5 * Run `icinga2 troubleshoot` to collect required troubleshooting information
   6 * Alternative, manual steps:
   7         * `icinga2 --version`
   8         * `icinga2 feature list`
   9         * `icinga2 daemon --validate`
  10         * Relevant output from your main and debug log ( `icinga2 object list --type='filelogger'` )
  11         * The newest Icinga 2 crash log, if relevant
  12         * Your icinga2.conf and, if you run multiple Icinga 2 instances, your zones.conf
  13 * How was Icinga 2 installed (and which repository in case) and which distribution are you using
  14 * Provide complete configuration snippets explaining your problem in detail
  15 * If the check command failed - what's the output of your manual plugin tests?
  16 * In case of [debugging](22-debug.md#debug) Icinga 2, the full back traces and outputs
  17
  18 ## <a id="troubleshooting-enable-debug-output"></a> Enable Debug Output
  19
  20 Enable the `debuglog` feature:
  21
  22     # icinga2 feature enable debuglog
  23     # service icinga2 restart
  24
  25 You can find the debug log file in `/var/log/icinga2/debug.log`.
  26
  27 Alternatively you may run Icinga 2 in the foreground with debugging enabled. Specify the console
  28 log severity as an additional parameter argument to `-x`.
  29
  30     # /usr/sbin/icinga2 daemon -x notice
  31
  32 The log level can be one of `critical`, `warning`, `information`, `notice`
  33 and `debug`.
  34
  35 ## <a id="list-configuration-objects"></a> List Configuration Objects
  36
  37 The `icinga2 object list` CLI command can be used to list all configuration objects and their
  38 attributes. The tool also shows where each of the attributes was modified.
  39
  40 That way you can also identify which objects have been created from your [apply rules](20-language-reference.md#apply).
  41
  42     # icinga2 object list
  43
  44     Object 'localhost!ssh' of type 'Service':
  45       * __name = 'localhost!ssh'
  46       * check_command = 'ssh'
  47         % = modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 5:3-5:23
  48       * check_interval = 60
  49         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 24:3-24:21
  50       * host_name = 'localhost'
  51         % = modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 4:3-4:25
  52       * max_check_attempts = 3
  53         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 23:3-23:24
  54       * name = 'ssh'
  55       * retry_interval = 30
  56         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 25:3-25:22
  57       * templates = [ 'ssh', 'generic-service' ]
  58         % += modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 1:0-7:1
  59         % += modified in '/etc/icinga2/conf.d/templates.conf', lines 22:1-26:1
  60       * type = 'Service'
  61       * vars
  62         % += modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 6:3-6:19
  63         * sla = '24x7'
  64           % = modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 6:3-6:19
  65
  66     [...]
  67
  68 You can also filter by name and type:
  69
  70     # icinga2 object list --name *ssh* --type Service
  71     Object 'localhost!ssh' of type 'Service':
  72       * __name = 'localhost!ssh'
  73       * check_command = 'ssh'
  74         % = modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 5:3-5:23
  75       * check_interval = 60
  76         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 24:3-24:21
  77       * host_name = 'localhost'
  78         % = modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 4:3-4:25
  79       * max_check_attempts = 3
  80         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 23:3-23:24
  81       * name = 'ssh'
  82       * retry_interval = 30
  83         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 25:3-25:22
  84       * templates = [ 'ssh', 'generic-service' ]
  85         % += modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 1:0-7:1
  86         % += modified in '/etc/icinga2/conf.d/templates.conf', lines 22:1-26:1
  87       * type = 'Service'
  88       * vars
  89         % += modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 6:3-6:19
  90         * sla = '24x7'
  91           % = modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 6:3-6:19
  92
  93     Found 1 Service objects.
  94
  95     [2014-10-15 14:27:19 +0200] information/cli: Parsed 175 objects.
  96
  97 ## <a id="check-command-definitions"></a> Where are the check command definitions?
  98
  99 Icinga 2 features a number of built-in [check command definitions](7-icinga-template-library.md#plugin-check-commands) which are
 100 included using
 101
 102     include <itl>
 103     include <plugins>
 104
 105 in the [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file. These files are not considered configuration files and will be overridden
 106 on upgrade, so please send modifications as proposed patches upstream. The default include path is set to
 107 `LocalStateDir + "/share/icinga2/includes"`.
 108
 109 You should add your own command definitions to a new file in `conf.d/` called `commands.conf`
 110 or similar.
 111
 112 ## <a id="checks-not-executed"></a> Checks are not executed
 113
 114 * Check the debug log to see if the check command gets executed
 115 * Verify that failed depedencies do not prevent command execution
 116 * Make sure that the plugin is executable by the Icinga 2 user (run a manual test)
 117 * Make sure the [checker](8-cli-commands.md#features) feature is enabled.
 118
 119 Examples:
 120
 121     # sudo -u icinga /usr/lib/nagios/plugins/check_ping -4 -H 127.0.0.1 -c 5000,100% -w 3000,80%
 122
 123     # icinga2 feature enable checker
 124     The feature 'checker' is already enabled.
 125
 126
 127 ## <a id="notifications-not-sent"></a> Notifications are not sent
 128
 129 * Check the debug log to see if a notification is triggered
 130 * If yes, verify that all conditions are satisfied
 131 * Are any errors on the notification command execution logged?
 132
 133 Verify the following configuration
 134
 135 * Is the host/service `enable_notifications` attribute set, and if, to which value?
 136 * Do the notification attributes `states`, `types`, `period` match the notification conditions?
 137 * Do the user attributes `states`, `types`, `period` match the notification conditions?
 138 * Are there any notification `begin` and `end` times configured?
 139 * Make sure the [notification](8-cli-commands.md#features) feature is enabled.
 140 * Does the referenced NotificationCommand work when executed as Icinga user on the shell?
 141
 142 If notifications are to be sent via mail make sure that the mail program specified exists.
 143 The name and location depends on the distribution so the preconfigured setting might have to be
 144 changed on your system.
 145
 146 Examples:
 147
 148     # icinga2 feature enable notification
 149     The feature 'notification' is already enabled.
 150
 151 ## <a id="feature-not-working"></a> Feature is not working
 152
 153 * Make sure that the feature configuration is enabled by symlinking from `features-available/`
 154 to `features-enabled` and that the latter is included in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf).
 155 * Are the feature attributes set correctly according to the documentation?
 156 * Any errors on the logs?
 157
 158 ## <a id="configuration-ignored"></a> Configuration is ignored
 159
 160 * Make sure that the line(s) are not [commented out](20-language-reference.md#comments) (starting with `//` or `#`, or
 161 encapsulated by `/* ... */`).
 162 * Is the configuration file included in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf)?
 163
 164 ## <a id="configuration-attribute-inheritance"></a> Configuration attributes are inherited from
 165
 166 Icinga 2 allows you to import templates using the [import](20-language-reference.md#template-imports) keyword. If these templates
 167 contain additional attributes, your objects will automatically inherit them. You can override
 168 or modify these attributes in the current object.
 169
 170 ## <a id="troubleshooting-cluster"></a> Cluster Troubleshooting
 171
 172 This applies to anything using the cluster protocol:
 173
 174 * [Distributed and High-Availability](13-distributed-monitoring-ha.md#distributed-monitoring-high-availability) scenarios
 175 * [Remote client](11-icinga2-client.md#icinga2-client-scenarios) scenarios
 176
 177 You should configure the [cluster health checks](13-distributed-monitoring-ha.md#cluster-health-check) if you haven't
 178 done so already.
 179
 180 > **Note**
 181 >
 182 > Some problems just exist due to wrong file permissions or packet filters applied. Make
 183 > sure to check these in the first place.
 184
 185 ### <a id="troubleshooting-cluster-connection-errors"></a> Cluster Troubleshooting Connection Errors
 186
 187 General connection errors normally lead you to one of the following problems:
 188
 189 * Wrong network configuration
 190 * Packet loss on the connection
 191 * Firewall rules preventing traffic
 192
 193 Use tools like `netstat`, `tcpdump`, `nmap`, etc to make sure that the cluster communication
 194 happens (default port is `5665`).
 195
 196     # tcpdump -n port 5665 -i any
 197
 198     # netstat -tulpen | grep icinga
 199
 200     # nmap yourclusternode.localdomain
 201
 202 ### <a id="troubleshooting-cluster-ssl-errors"></a> Cluster Troubleshooting SSL Errors
 203
 204 If the cluster communication fails with SSL error messages, make sure to check
 205 the following
 206
 207 * File permissions on the SSL certificate files
 208 * Does the used CA match for all cluster endpoints?
 209   * Verify the `Issuer` being your trusted CA
 210   * Verify the `Subject` containing your endpoint's common name (CN)
 211   * Check the validity of the certificate itself
 212
 213 Steps on the client `icinga2-node2.localdomain`:
 214
 215     # ls -la /etc/icinga2/pki
 216
 217     # cd /etc/icinga2/pki/
 218     # openssl x509 -in icinga2-node2.localdomain.crt -text
 219     Certificate:
 220         Data:
 221             Version: 1 (0x0)
 222             Serial Number: 2 (0x2)
 223         Signature Algorithm: sha1WithRSAEncryption
 224             Issuer: C=DE, ST=Bavaria, L=Nuremberg, O=NETWAYS GmbH, OU=Monitoring, CN=Icinga CA
 225             Validity
 226                 Not Before: Jan  7 13:17:38 2014 GMT
 227                 Not After : Jan  5 13:17:38 2024 GMT
 228             Subject: C=DE, ST=Bavaria, L=Nuremberg, O=NETWAYS GmbH, OU=Monitoring, CN=icinga2-node2.localdomain
 229             Subject Public Key Info:
 230                 Public Key Algorithm: rsaEncryption
 231                     Public-Key: (4096 bit)
 232                     Modulus:
 233                     ...
 234
 235 Try to manually connect from `icinga2-node2.localdomain` to the master node `icinga2-node1.localdomain`:
 236
 237     # openssl s_client -CAfile /etc/icinga2/pki/ca.crt -cert /etc/icinga2/pki/icinga2-node2.localdomain.crt -key /etc/icinga2/pki/icinga2-node2.localdomain..key -connect icinga2-node1.localdomain.crt:5665
 238
 239     CONNECTED(00000003)
 240     ---
 241     ...
 242
 243 If the connection attempt fails or your CA does not match, [verify the master and client certificates](17-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification).
 244
 245 #### <a id="troubleshooting-cluster-unauthenticated-clients"></a> Cluster Troubleshooting Unauthenticated Clients
 246
 247 Unauthenticated nodes are able to connect required by the
 248 [CSR auto-signing](11-icinga2-client.md#csr-autosigning-requirements) functionality.
 249
 250 Master:
 251
 252     [2015-07-13 18:29:25 +0200] information/ApiListener: New client connection for identity 'icinga-client' (unauthenticated)
 253
 254 Client as command execution bridge:
 255
 256     [2015-07-13 18:29:26 +1000] notice/ApiEvents: Discarding 'execute command' message from 'icinga-master': Invalid endpoint origin (client not allowed).
 257
 258 If these messages do not go away, make sure to [verify the master and client certificates](17-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification).
 259
 260 #### <a id="troubleshooting-cluster-ssl-certificate-verification"></a> Cluster Troubleshooting SSL Certificate Verification
 261
 262 Make sure to verify the client's certificate and its received `ca.crt` in `/etc/icinga2/pki` and ensure that
 263 both instances are signed by the **same CA**.
 264
 265     # openssl verify -verbose -CAfile /etc/icinga2/pki/ca.crt /etc/icinga2/pki/icinga2-node1.localdomain.crt
 266     icinga2-node1.localdomain.crt: OK
 267
 268     # openssl verify -verbose -CAfile /etc/icinga2/pki/ca.crt /etc/icinga2/pki/icinga2-node2.localdomain.crt
 269     icinga2-node2.localdomain.crt: OK
 270
 271 Fetch the `ca.crt` file from the client node and compare it to your master's `ca.crt` file:
 272
 273     # scp icinga2-node2:/etc/icinga2/pki/ca.crt test-client-ca.crt
 274     # diff -ur /etc/icinga2/pki/ca.crt test-client-ca.crt
 275
 276 On SLES11 you'll need to use the `openssl1` command instead of `openssl`.
 277
 278 ### <a id="troubleshooting-cluster-message-errors"></a> Cluster Troubleshooting Message Errors
 279
 280 At some point, when the network connection is broken or gone, the Icinga 2 instances
 281 will be disconnected. If the connection can't be re-established between zones and endpoints,
 282 they remain in a Split-Brain-mode and history may differ.
 283
 284 Although the Icinga 2 cluster protocol stores historical events in a [replay log](17-troubleshooting.md#troubleshooting-cluster-replay-log)
 285 for later synchronisation, you should make sure to check why the network connection failed.
 286
 287 ### <a id="troubleshooting-cluster-command-endpoint-errors"></a> Cluster Troubleshooting Command Endpoint Errors
 288
 289 Command endpoints can be used for clients acting as [remote command execution bridge](11-icinga2-client.md#icinga2-client-configuration-command-bridge)
 290 as well as inside an [High-Availability cluster](13-distributed-monitoring-ha.md#distributed-monitoring-high-availability).
 291
 292 There is no cli command for manually executing the check, but you can verify
 293 the following (e.g. by invoking a forced check from the web interface):
 294
 295 * `/var/log/icinga2/icinga2.log` contains connection and execution errors.
 296  * The ApiListener is not enabled to [accept commands](#clients-as-command-execution-bridge).
 297  * `CheckCommand` definition not found on the remote client.
 298  * Referenced check plugin not found on the remote client.
 299  * Runtime warnings and errors, e.g. unresolved runtime macros or configuration problems.
 300 * Specific error messages are also populated into `UNKNOWN` check results including a detailed error message in their output.
 301 * More verbose logs are found inside the [debug log](17-troubleshooting.md#troubleshooting-enable-debug-output).
 302
 303 ### <a id="troubleshooting-cluster-config-sync"></a> Cluster Troubleshooting Config Sync
 304
 305 If the cluster zones do not sync their configuration, make sure to check the following:
 306
 307 * Within a config master zone, only one configuration master is allowed to have its config in `/etc/icinga2/zones.d`.
 308 ** The master syncs the configuration to `/var/lib/icinga2/api/zones/` during startup and only syncs valid configuration to the other nodes.
 309 ** The other nodes receive the configuration into `/var/lib/icinga2/api/zones/`.
 310 * The `icinga2.log` log file in `/var/log/icinga2` will indicate whether this ApiListener
 311 [accepts config](13-distributed-monitoring-ha.md#zone-config-sync-permissions), or not.
 312
 313 ### <a id="troubleshooting-cluster-replay-log"></a> Cluster Troubleshooting Overdue Check Results
 314
 315 If your master does not receive check results (or any other events) from the child zones
 316 (satellite, clients, etc) make sure to check whether the client sending in events
 317 is allowed to do so.
 318
 319 The [cluster naming convention](13-distributed-monitoring-ha.md#cluster-naming-convention)
 320 applies so if there's a mismatch between your client node's endpoint name and its provided
 321 certificate's CN, the master will deny all events.
 322
 323 > **Tip**
 324 >
 325 > [Icinga Web 2](2-getting-started.md#setting-up-the-user-interface) provides a dashboard view
 326 > for overdue check results.
 327
 328 Enable the [debug log](17-troubleshooting.md#troubleshooting-enable-debug-output) on the master
 329 for more verbose insights.
 330
 331 If the client cannot authenticate, it's a more general [problem](17-troubleshooting.md#troubleshooting-cluster-unauthenticated-clients).
 332
 333 The client's endpoint is not configured on nor trusted by the master node:
 334
 335     Discarding 'check result' message from 'icinga2b': Invalid endpoint origin (client not allowed).
 336
 337 The check result message sent by the client does not belong to the zone the checkable object is
 338 in on the master:
 339
 340     Discarding 'check result' message from 'icinga2b': Unauthorized access.
 341
 342
 343 ### <a id="troubleshooting-cluster-replay-log"></a> Cluster Troubleshooting Replay Log
 344
 345 If your `/var/lib/icinga2/api/log` directory grows, it generally means that your cluster
 346 cannot replay the log on connection loss and re-establishment. A master node for example
 347 will store all events for not connected endpoints in the same and child zones.
 348
 349 Check the following:
 350
 351 * All clients are connected? (e.g. [cluster health check](13-distributed-monitoring-ha.md#cluster-health-check)).
 352 * Check your [connection](17-troubleshooting.md#troubleshooting-cluster-connection-errors) in general.
 353 * Does the log replay work, e.g. are all events processed and the directory gets cleared up over time?
 354 * Decrease the `log_duration` attribute value for that specific [endpoint](6-object-types.md#objecttype-endpoint).