If you want to help update this documentation please read
[this howto](https://wiki.icinga.org/display/community/Update+the+Icinga+2+documentation).
-### <a id="development"></a> Icinga 2 Development
+### <a id="development-info"></a> Icinga 2 Development
You can follow Icinga 2's development closely by checking
out these resources:
and specific trap handlers passing the check results to Icinga 2.
Following the SNMPTT [Format](http://snmptt.sourceforge.net/docs/snmptt.shtml#SNMPTT.CONF-FORMAT)
-documentation and the Icinga external command syntax found [here](22-appendix.md#external-commands-list-detail)
+documentation and the Icinga external command syntax found [here](23-appendix.md#external-commands-list-detail)
we can create generic services that can accommodate any number of hosts for a given scenario.
### <a id="simple-traps"></a> Simple SNMP Traps
(1 Zeile)
-A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](22-appendix.md#schema-db-ido).
+A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](23-appendix.md#schema-db-ido).
## <a id="external-commands"></a> External Commands
Oct 17 15:01:25 icinga-server icinga2: Executing external command: [1382014885] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;1382014885
Oct 17 15:01:25 icinga-server icinga2: Rescheduling next check for service 'ping4'
-A list of currently supported external commands can be found [here](22-appendix.md#external-commands-list-detail).
+A list of currently supported external commands can be found [here](23-appendix.md#external-commands-list-detail).
Detailed information on the commands and their required parameters can be found
on the [Icinga 1.x documentation](http://docs.icinga.org/latest/en/extcommands2.html).
Livestatus.
Details on the available tables and attributes with Icinga 2 can be found
-in the [Livestatus Schema](22-appendix.md#schema-livestatus) section.
+in the [Livestatus Schema](23-appendix.md#schema-livestatus) section.
You can enable Livestatus using icinga2 feature enable:
### <a id="livestatus-command-queries"></a> Livestatus COMMAND Queries
-A list of available external commands and their parameters can be found [here](22-appendix.md#external-commands-list-detail)
+A list of available external commands and their parameters can be found [here](23-appendix.md#external-commands-list-detail)
$ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects.
-A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](22-appendix.md#schema-livestatus).
+A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](23-appendix.md#schema-livestatus).
## <a id="status-data"></a> Status Data Files
* How was Icinga 2 installed (and which repository in case) and which distribution are you using
* Provide complete configuration snippets explaining your problem in detail
* If the check command failed - what's the output of your manual plugin tests?
-* In case of [debugging](20-debug.md#debug) Icinga 2, the full back traces and outputs
+* In case of [debugging](21-development.md#development) Icinga 2, the full back traces and outputs
## <a id="troubleshooting-enable-debug-output"></a> Enable Debug Output
--- /dev/null
+# <a id="script-debugger"></a> Script Debugger
+
+You can run the Icinga 2 daemon with the `-X` (`--script-debugger`)
+parameter to enable the script debugger:
+
+ # icinga2 daemon -X
+
+When an exception occurs or the [debugger](18-language-reference.md#breakpoints)
+keyword is encountered in a user script Icinga 2 launches a console that
+allows the user to debug the script.
+
+Here is a list of common error which can be diagnosed with the script debugger:
+
+* Configuration errors (apply)
+* Errors in user-defined functions
+
+## <a id="script-debugger-config-errors"></a> Debugging Configuration Errors
+
+The following example illustrates the problem of a service [apply rule](3-monitoring-basics.md#using-apply-for)
+which expects a dictionary value for `config`, but the host custom attribute only
+provides a string value:
+
+ object Host "script-debugger-host" {
+ check_command = "icinga"
+
+ vars.http_vhosts["example.org"] = "192.168.1.100" // a string value
+ }
+
+ apply Service for (http_vhost => config in host.vars.http_vhosts) {
+ import "generic-service"
+
+ vars += config // expects a dictionary
+
+ check_command = "http"
+ }
+
+The error message on config validation will warn about the wrong value type,
+but does not provide any context which objects are affected.
+
+Enable the script debugger and run the config validation:
+
+ # icinga2 daemon -C -X
+
+ Breakpoint encountered in /etc/icinga2/conf.d/services.conf: 59:67-65:1
+ Exception: Error: Error while evaluating expression: Cannot convert value of type 'String' to an object.
+ Location:
+ /etc/icinga2/conf.d/services.conf(62): check_command = "http"
+ /etc/icinga2/conf.d/services.conf(63):
+ /etc/icinga2/conf.d/services.conf(64): vars += config
+ ^^^^^^^^^^^^^^
+ /etc/icinga2/conf.d/services.conf(65): }
+ /etc/icinga2/conf.d/services.conf(66):
+ You can inspect expressions (such as variables) by entering them at the prompt.
+ To leave the debugger and continue the program use "$continue".
+ <1> =>
+
+You can print the variables `vars` and `config` to get an idea about
+their values:
+
+ <1> => vars
+ null
+ <2> => config
+ "192.168.1.100"
+ <3> =>
+
+The `vars` attribute has to be a dictionary. Trying to set this attribute to a string caused
+the error in our configuration example.
+
+In order to determine the name of the host where the value of the `config` variable came from
+you can inspect attributes of the service object:
+
+ <3> => host_name
+ "script-debugger-host-01"
+ <4> => name
+ "http"
+
+Additionally you can view the service object attributes by printing the value of `this`.
+
+## <a id="script-debugger-breakpoints"></a> Using Breakpoints
+
+In order to halt execution in a script you can use the `debugger` keyword:
+
+ object Host "script-debugger-host-02" {
+ check_command = "dummy"
+ check_interval = 5s
+
+ vars.dummy_text = {{
+ var text = "Hello from " + macro("$name$")
+ debugger
+ return text
+ }}
+ }
+
+Icinga 2 will spawn a debugger console every time the function is executed:
+
+ # icinga2 daemon -X
+ ...
+ Breakpoint encountered in /etc/icinga2/tests/script-debugger.conf: 7:5-7:12
+ You can inspect expressions (such as variables) by entering them at the prompt.
+ To leave the debugger and continue the program use "$continue".
+ <1> => text
+ "Hello from script-debugger-host-02"
+ <2> => $continue
+
+
-# <a id="debug"></a> Debug Icinga 2
+# <a id="development"></a> Develop Icinga 2
+
+This chapter provides hints on Icinga 2 development
+especially for debugging purposes.
> **Note**
>
For a long-term migration of your configuration you should consider re-creating
your configuration based on the proposed Icinga 2 configuration paradigm.
-Please read the [next chapter](21-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences
+Please read the [next chapter](22-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences
between 1.x and 2.
### <a id="manual-config-migration-hints"></a> Manual Config Migration Hints
straight into a possible Icinga 2 format. If you found a different strategy, please
let us know!
-If you require in-depth explanations, please check the [next chapter](21-migrating-from-icinga-1x.md#differences-1x-2).
+If you require in-depth explanations, please check the [next chapter](22-migrating-from-icinga-1x.md#differences-1x-2).
#### <a id="manual-config-migration-hints-Intervals"></a> Manual Config Migration Hints for Intervals
#### <a id="manual-config-migration-hints-runtime-macros"></a> Manual Config Migration Hints for Runtime Macros
-Runtime macros have been renamed. A detailed comparison table can be found [here](21-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros).
+Runtime macros have been renamed. A detailed comparison table can be found [here](22-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros).
For example, accessing the service check output looks like the following in Icinga 1.x:
#### <a id="manual-config-migration-hints-contacts-users"></a> Manual Config Migration Hints for Contacts (Users)
Contacts in Icinga 1.x act as users in Icinga 2, but do not have any notification commands specified.
-This migration part is explained in the [next chapter](21-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications).
+This migration part is explained in the [next chapter](22-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications).
define contact{
contact_name testconfig-user
email icinga@localhost
}
-The `service_notification_options` can be [mapped](21-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters)
+The `service_notification_options` can be [mapped](22-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters)
into generic `state` and `type` filters, if additional notification filtering is required. `alias` gets
renamed to `display_name`.
Convert the `notification_options` attribute from Icinga 1.x to Icinga 2 `states` and `types`. Details
-[here](21-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters). Add the notification period.
+[here](22-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters). Add the notification period.
states = [ OK, Warning, Critical ]
types = [ Recovery, Problem, Custom ]
assign where "hg_svcdep2" in host.groups
}
-Host dependencies are explained in the [next chapter](21-migrating-from-icinga-1x.md#manual-config-migration-hints-host-parents).
+Host dependencies are explained in the [next chapter](22-migrating-from-icinga-1x.md#manual-config-migration-hints-host-parents).
are separated from the command name using an exclamation mark (`!`).
Please check the migration hints for a detailed
-[migration example](21-migrating-from-icinga-1x.md#manual-config-migration-hints-check-command-arguments).
+[migration example](22-migrating-from-icinga-1x.md#manual-config-migration-hints-check-command-arguments).
> **Note**
>
dependency will fail and render all child objects (hosts or services) unreachable.
You can determine the child's reachability by querying the `is_reachable` attribute
-in for example [DB IDO](22-appendix.md#schema-db-ido-extensions).
+in for example [DB IDO](23-appendix.md#schema-db-ido-extensions).
### <a id="dependencies-implicit-host-service"></a> Implicit Dependencies for Services on Host
> which will validate the configuration in a separate process and not stop
> the other events like check execution, notifications, etc.
>
-> Details can be found [here](21-migrating-from-icinga-1x.md#differences-1x-2-real-reload).
+> Details can be found [here](22-migrating-from-icinga-1x.md#differences-1x-2-real-reload).
- [17-upgrading-icinga-2.md, Upgrading Icinga 2]
- [18-language-reference.md, Language Reference]
- [19-library-reference.md, Library Reference]
-- [20-debug.md, Debug]
-- [21-migrating-from-icinga-1x.md, Migrating from Icinga 1.x]
-- [22-appendix.md, Appendix]
+- [20-script-debugger.md, Script Debugger]
+- [21-development.md, Development]
+- [22-migrating-from-icinga-1x.md, Migrating from Icinga 1.x]
+- [23-appendix.md, Appendix]
theme: readthedocs
markdown_extensions: [smarty]
extra_javascript: [scroll.js]
projects / icinga2 / commitdiff