granicus.if.org Git - icinga2/blob - doc/15-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](20-development.md#development) 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 > **Tip**
  41 >
  42 > Use the Icinga 2 API to access [config objects at runtime](12-icinga2-api.md#icinga2-api-config-objects) directly.
  43
  44 That way you can also identify which objects have been created from your [apply rules](17-language-reference.md#apply).
  45
  46     # icinga2 object list
  47
  48     Object 'localhost!ssh' of type 'Service':
  49       * __name = 'localhost!ssh'
  50       * check_command = 'ssh'
  51         % = modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 5:3-5:23
  52       * check_interval = 60
  53         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 24:3-24:21
  54       * host_name = 'localhost'
  55         % = modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 4:3-4:25
  56       * max_check_attempts = 3
  57         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 23:3-23:24
  58       * name = 'ssh'
  59       * retry_interval = 30
  60         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 25:3-25:22
  61       * templates = [ 'ssh', 'generic-service' ]
  62         % += modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 1:0-7:1
  63         % += modified in '/etc/icinga2/conf.d/templates.conf', lines 22:1-26:1
  64       * type = 'Service'
  65       * vars
  66         % += modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 6:3-6:19
  67         * sla = '24x7'
  68           % = modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 6:3-6:19
  69
  70     [...]
  71
  72 You can also filter by name and type:
  73
  74     # icinga2 object list --name *ssh* --type Service
  75     Object 'localhost!ssh' of type 'Service':
  76       * __name = 'localhost!ssh'
  77       * check_command = 'ssh'
  78         % = modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 5:3-5:23
  79       * check_interval = 60
  80         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 24:3-24:21
  81       * host_name = 'localhost'
  82         % = modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 4:3-4:25
  83       * max_check_attempts = 3
  84         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 23:3-23:24
  85       * name = 'ssh'
  86       * retry_interval = 30
  87         % = modified in '/etc/icinga2/conf.d/templates.conf', lines 25:3-25:22
  88       * templates = [ 'ssh', 'generic-service' ]
  89         % += modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 1:0-7:1
  90         % += modified in '/etc/icinga2/conf.d/templates.conf', lines 22:1-26:1
  91       * type = 'Service'
  92       * vars
  93         % += modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 6:3-6:19
  94         * sla = '24x7'
  95           % = modified in '/etc/icinga2/conf.d/hosts/localhost/ssh.conf', lines 6:3-6:19
  96
  97     Found 1 Service objects.
  98
  99     [2014-10-15 14:27:19 +0200] information/cli: Parsed 175 objects.
 100
 101 ## <a id="check-command-definitions"></a> Where are the check command definitions?
 102
 103 Icinga 2 features a number of built-in [check command definitions](10-icinga-template-library.md#plugin-check-commands) which are
 104 included using
 105
 106     include <itl>
 107     include <plugins>
 108
 109 in the [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file. These files are not considered configuration files and will be overridden
 110 on upgrade, so please send modifications as proposed patches upstream. The default include path is set to
 111 `LocalStateDir + "/share/icinga2/includes"`.
 112
 113 You should add your own command definitions to a new file in `conf.d/` called `commands.conf`
 114 or similar.
 115
 116 ## <a id="troubleshooting-checks"></a> Checks
 117
 118 ### <a id="checks-executed-command"></a> Executed Command for Checks
 119
 120 * Use the Icinga 2 API to [query](12-icinga2-api.md#icinga2-api-config-objects-query) host/service objects
 121 for their check result containing the executed shell command.
 122 * Use the Icinga 2 [console cli command](11-cli-commands.md#cli-command-console)
 123 to fetch the checkable object, its check result and the executed shell command.
 124 * Alternatively enable the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) and look for the executed command.
 125
 126 Example for a service object query using a [regex match]() on the name:
 127
 128     $ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/services' \
 129     -d '{ "filter": "regex(pattern, service.name)", "filter_vars": { "pattern": "^http" }, "attrs": [ "__name", "last_check_result" ] }' | python -m json.tool
 130     {
 131         "results": [
 132             {
 133                 "attrs": {
 134                     "__name": "example.localdomain!http",
 135                     "last_check_result": {
 136                         "active": true,
 137                         "check_source": "example.localdomain",
 138                         "command": [
 139                             "/usr/local/sbin/check_http",
 140                             "-I",
 141                             "127.0.0.1",
 142                             "-u",
 143                             "/"
 144                         ],
 145
 146       ...
 147
 148                     }
 149                 },
 150                 "joins": {},
 151                 "meta": {},
 152                 "name": "example.localdomain!http",
 153                 "type": "Service"
 154             }
 155         ]
 156     }
 157
 158 Example for using the `icinga2 console` CLI command evaluation functionality:
 159
 160     $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/' \
 161     --eval 'get_service("example.localdomain", "http").last_check_result.command' | python -m json.tool
 162     [
 163         "/usr/local/sbin/check_http",
 164         "-I",
 165         "127.0.0.1",
 166         "-u",
 167         "/"
 168     ]
 169
 170 Example for searching the debug log:
 171
 172     # icinga2 feature enable debuglog
 173     # systemctl restart icinga2
 174     # tail -f /var/log/icinga2/debug.log | grep "notice/Process"
 175
 176
 177 ### <a id="checks-not-executed"></a> Checks are not executed
 178
 179 * Check the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) to see if the check command gets executed.
 180 * Verify that failed depedencies do not prevent command execution.
 181 * Make sure that the plugin is executable by the Icinga 2 user (run a manual test).
 182 * Make sure the [checker](11-cli-commands.md#enable-features) feature is enabled.
 183 * Use the Icinga 2 API [event streams](12-icinga2-api.md#icinga2-api-event-streams) to receive live check result streams.
 184
 185 Examples:
 186
 187     # sudo -u icinga /usr/lib/nagios/plugins/check_ping -4 -H 127.0.0.1 -c 5000,100% -w 3000,80%
 188
 189     # icinga2 feature enable checker
 190     The feature 'checker' is already enabled.
 191
 192 Fetch all check result events matching the `event.service` name `random`:
 193
 194     $ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/events?queue=debugchecks&types=CheckResult&filter=match%28%22random*%22,event.service%29'
 195
 196
 197 ## <a id="notifications-not-sent"></a> Notifications are not sent
 198
 199 * Check the debug log to see if a notification is triggered.
 200 * If yes, verify that all conditions are satisfied.
 201 * Are any errors on the notification command execution logged?
 202
 203 Verify the following configuration:
 204
 205 * Is the host/service `enable_notifications` attribute set, and if so, to which value?
 206 * Do the notification attributes `states`, `types`, `period` match the notification conditions?
 207 * Do the user attributes `states`, `types`, `period` match the notification conditions?
 208 * Are there any notification `begin` and `end` times configured?
 209 * Make sure the [notification](11-cli-commands.md#enable-features) feature is enabled.
 210 * Does the referenced NotificationCommand work when executed as Icinga user on the shell?
 211
 212 If notifications are to be sent via mail, make sure that the mail program specified inside the
 213 [NotificationCommand object](9-object-types.md#objecttype-notificationcommand) exists.
 214 The name and location depends on the distribution so the preconfigured setting might have to be
 215 changed on your system.
 216
 217
 218 Examples:
 219
 220     # icinga2 feature enable notification
 221     The feature 'notification' is already enabled.
 222
 223 You can use the Icinga 2 API [event streams](12-icinga2-api.md#icinga2-api-event-streams) to receive live notification streams:
 224
 225     $ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/events?queue=debugnotifications&types=Notification'
 226
 227
 228 ## <a id="feature-not-working"></a> Feature is not working
 229
 230 * Make sure that the feature configuration is enabled by symlinking from `features-available/`
 231 to `features-enabled` and that the latter is included in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf).
 232 * Are the feature attributes set correctly according to the documentation?
 233 * Any errors on the logs?
 234
 235 ## <a id="configuration-ignored"></a> Configuration is ignored
 236
 237 * Make sure that the line(s) are not [commented out](17-language-reference.md#comments) (starting with `//` or `#`, or
 238 encapsulated by `/* ... */`).
 239 * Is the configuration file included in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf)?
 240
 241 ## <a id="configuration-attribute-inheritance"></a> Configuration attributes are inherited from
 242
 243 Icinga 2 allows you to import templates using the [import](17-language-reference.md#template-imports) keyword. If these templates
 244 contain additional attributes, your objects will automatically inherit them. You can override
 245 or modify these attributes in the current object.
 246
 247 ## <a id="configuration-value-dollar-sign"></a> Configuration Value with Single Dollar Sign
 248
 249 In case your configuration validation fails with a missing closing dollar sign error message, you
 250 did not properly escape the single dollar sign preventing its usage as [runtime macro](3-monitoring-basics.md#runtime-macros).
 251
 252     critical/config: Error: Validation failed for Object 'ping4' (Type: 'Service') at /etc/icinga2/zones.d/global-templates/windows.conf:24: Closing $ not found in macro format string 'top-syntax=${list}'.
 253
 254
 255 ## <a id="troubleshooting-cluster"></a> Cluster and Clients Troubleshooting
 256
 257 This applies to any Icinga 2 node in a [distributed monitoring setup](6-distributed-monitoring.md#distributed-monitoring-scenarios).
 258
 259 You should configure the [cluster health checks](6-distributed-monitoring.md#distributed-monitoring-health-checks) if you haven't
 260 done so already.
 261
 262 > **Note**
 263 >
 264 > Some problems just exist due to wrong file permissions or packet filters applied. Make
 265 > sure to check these in the first place.
 266
 267 ### <a id="troubleshooting-cluster-connection-errors"></a> Cluster Troubleshooting Connection Errors
 268
 269 General connection errors normally lead you to one of the following problems:
 270
 271 * Wrong network configuration
 272 * Packet loss on the connection
 273 * Firewall rules preventing traffic
 274
 275 Use tools like `netstat`, `tcpdump`, `nmap`, etc. to make sure that the cluster communication
 276 happens (default port is `5665`).
 277
 278     # tcpdump -n port 5665 -i any
 279
 280     # netstat -tulpen | grep icinga
 281
 282     # nmap yourclusternode.localdomain
 283
 284 ### <a id="troubleshooting-cluster-ssl-errors"></a> Cluster Troubleshooting SSL Errors
 285
 286 If the cluster communication fails with SSL error messages, make sure to check
 287 the following
 288
 289 * File permissions on the SSL certificate files
 290 * Does the used CA match for all cluster endpoints?
 291   * Verify the `Issuer` being your trusted CA
 292   * Verify the `Subject` containing your endpoint's common name (CN)
 293   * Check the validity of the certificate itself
 294
 295 Steps on the client `icinga2-node2.localdomain`:
 296
 297     # ls -la /etc/icinga2/pki
 298
 299     # cd /etc/icinga2/pki/
 300     # openssl x509 -in icinga2-node2.localdomain.crt -text
 301     Certificate:
 302         Data:
 303             Version: 1 (0x0)
 304             Serial Number: 2 (0x2)
 305         Signature Algorithm: sha1WithRSAEncryption
 306             Issuer: C=DE, ST=Bavaria, L=Nuremberg, O=NETWAYS GmbH, OU=Monitoring, CN=Icinga CA
 307             Validity
 308                 Not Before: Jan  7 13:17:38 2014 GMT
 309                 Not After : Jan  5 13:17:38 2024 GMT
 310             Subject: C=DE, ST=Bavaria, L=Nuremberg, O=NETWAYS GmbH, OU=Monitoring, CN=icinga2-node2.localdomain
 311             Subject Public Key Info:
 312                 Public Key Algorithm: rsaEncryption
 313                     Public-Key: (4096 bit)
 314                     Modulus:
 315                     ...
 316
 317 Try to manually connect from `icinga2-node2.localdomain` to the master node `icinga2-node1.localdomain`:
 318
 319     # 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:5665
 320
 321     CONNECTED(00000003)
 322     ---
 323     ...
 324
 325 If the connection attempt fails or your CA does not match, [verify the master and client certificates](15-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification).
 326
 327 #### <a id="troubleshooting-cluster-unauthenticated-clients"></a> Cluster Troubleshooting Unauthenticated Clients
 328
 329 Unauthenticated nodes are able to connect. This is required for client setups.
 330
 331 Master:
 332
 333     [2015-07-13 18:29:25 +0200] information/ApiListener: New client connection for identity 'icinga-client' (unauthenticated)
 334
 335 Client as command execution bridge:
 336
 337     [2015-07-13 18:29:26 +1000] notice/ApiEvents: Discarding 'execute command' message from 'icinga-master': Invalid endpoint origin (client not allowed).
 338
 339 If these messages do not go away, make sure to [verify the master and client certificates](15-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification).
 340
 341 #### <a id="troubleshooting-cluster-ssl-certificate-verification"></a> Cluster Troubleshooting SSL Certificate Verification
 342
 343 Make sure to verify the client's certificate and its received `ca.crt` in `/etc/icinga2/pki` and ensure that
 344 both instances are signed by the **same CA**.
 345
 346     # openssl verify -verbose -CAfile /etc/icinga2/pki/ca.crt /etc/icinga2/pki/icinga2-node1.localdomain.crt
 347     icinga2-node1.localdomain.crt: OK
 348
 349     # openssl verify -verbose -CAfile /etc/icinga2/pki/ca.crt /etc/icinga2/pki/icinga2-node2.localdomain.crt
 350     icinga2-node2.localdomain.crt: OK
 351
 352 Fetch the `ca.crt` file from the client node and compare it to your master's `ca.crt` file:
 353
 354     # scp icinga2-node2:/etc/icinga2/pki/ca.crt test-client-ca.crt
 355     # diff -ur /etc/icinga2/pki/ca.crt test-client-ca.crt
 356
 357 On SLES11 you'll need to use the `openssl1` command instead of `openssl`.
 358
 359 ### <a id="troubleshooting-cluster-message-errors"></a> Cluster Troubleshooting Message Errors
 360
 361 At some point, when the network connection is broken or gone, the Icinga 2 instances
 362 will be disconnected. If the connection can't be re-established between endpoints in the same HA zone,
 363 they remain in a Split-Brain-mode and history may differ.
 364
 365 Although the Icinga 2 cluster protocol stores historical events in a [replay log](15-troubleshooting.md#troubleshooting-cluster-replay-log)
 366 for later synchronisation, you should make sure to check why the network connection failed.
 367
 368 ### <a id="troubleshooting-cluster-command-endpoint-errors"></a> Cluster Troubleshooting Command Endpoint Errors
 369
 370 Command endpoints can be used [for clients](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint)
 371 as well as inside an [High-Availability cluster](6-distributed-monitoring.md#distributed-monitoring-scenarios).
 372
 373 There is no cli command for manually executing the check, but you can verify
 374 the following (e.g. by invoking a forced check from the web interface):
 375
 376 * `/var/log/icinga2/icinga2.log` contains connection and execution errors.
 377  * The ApiListener is not enabled to [accept commands](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint).
 378  * `CheckCommand` definition not found on the remote client.
 379  * Referenced check plugin not found on the remote client.
 380  * Runtime warnings and errors, e.g. unresolved runtime macros or configuration problems.
 381 * Specific error messages are also populated into `UNKNOWN` check results including a detailed error message in their output.
 382 * Verify the `check_source` object attribute. This is populated by the node executing the check.
 383 * More verbose logs are found inside the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output).
 384
 385 * Use the Icinga 2 API [event streams](12-icinga2-api.md#icinga2-api-event-streams) to receive live check result streams.
 386
 387 Fetch all check result events matching the `event.service` name `remote-client`:
 388
 389     $ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/events?queue=debugcommandendpoint&types=CheckResult&filter=match%28%22remote-client*%22,event.service%29'
 390
 391
 392
 393 ### <a id="troubleshooting-cluster-config-sync"></a> Cluster Troubleshooting Config Sync
 394
 395 If the cluster zones do not sync their configuration, make sure to check the following:
 396
 397 * Within a config master zone, only one configuration master is allowed to have its config in `/etc/icinga2/zones.d`.
 398 ** The master syncs the configuration to `/var/lib/icinga2/api/zones/` during startup and only syncs valid configuration to the other nodes.
 399 ** The other nodes receive the configuration into `/var/lib/icinga2/api/zones/`.
 400 * The `icinga2.log` log file in `/var/log/icinga2` will indicate whether this ApiListener
 401 [accepts config](6-distributed-monitoring.md#distributed-monitoring-top-down-config-sync), or not.
 402
 403 Verify the object's [version](9-object-types.md#object-types) attribute on all nodes to
 404 check whether the config update and reload was succesful or not.
 405
 406 ### <a id="troubleshooting-cluster-check-results"></a> Cluster Troubleshooting Overdue Check Results
 407
 408 If your master does not receive check results (or any other events) from the child zones
 409 (satellite, clients, etc.), make sure to check whether the client sending in events
 410 is allowed to do so.
 411
 412 The [distributed monitoring conventions](6-distributed-monitoring.md#distributed-monitoring-conventions)
 413 apply. So, if there's a mismatch between your client node's endpoint name and its provided
 414 certificate's CN, the master will deny all events.
 415
 416 > **Tip**
 417 >
 418 > [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2) provides a dashboard view
 419 > for overdue check results.
 420
 421 Enable the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) on the master
 422 for more verbose insights.
 423
 424 If the client cannot authenticate, it's a more general [problem](15-troubleshooting.md#troubleshooting-cluster-unauthenticated-clients).
 425
 426 The client's endpoint is not configured on nor trusted by the master node:
 427
 428     Discarding 'check result' message from 'icinga2b': Invalid endpoint origin (client not allowed).
 429
 430 The check result message sent by the client does not belong to the zone the checkable object is
 431 in on the master:
 432
 433     Discarding 'check result' message from 'icinga2b': Unauthorized access.
 434
 435
 436 ### <a id="troubleshooting-cluster-replay-log"></a> Cluster Troubleshooting Replay Log
 437
 438 If your `/var/lib/icinga2/api/log` directory grows, it generally means that your cluster
 439 cannot replay the log on connection loss and re-establishment. A master node for example
 440 will store all events for not connected endpoints in the same and child zones.
 441
 442 Check the following:
 443
 444 * All clients are connected? (e.g. [cluster health check](6-distributed-monitoring.md#distributed-monitoring-health-checks)).
 445 * Check your [connection](15-troubleshooting.md#troubleshooting-cluster-connection-errors) in general.
 446 * Does the log replay work, e.g. are all events processed and the directory gets cleared up over time?
 447 * Decrease the `log_duration` attribute value for that specific [endpoint](9-object-types.md#objecttype-endpoint).