<commit_before>
:imagesdir: ../../../images

[[omd-gearman]]
==== Gearman forwarder
[#git-edit-section]
:page-path: docs/manual/integration/monitoring/omd-gearman.adoc
git-link:{page-path}{git-view} | git-link:{page-path}{git-edit}

This page describes how the results of Sakuli tests can be transmitted directly into the *Gearman result queue* of a monitoring system.

NOTE: If you do not use a gearman-enabled monitoring system in a https://labs.consol.de/OMD/[OMD] environment, the procedure may vary.

image:sakuli-gearman.png[sakuli-db-forwarder]


===== OMD Configuration

====== Enable and configure mod-gearman

Use the Makefile located in `$OMD_ROOT/share/sakuli/` to configure mod_gearman:

* enable all services for mod_gearman
* set the bind IP and port (default: `0.0.0.0:4730`; overwrite with e.g. `export GEARMAND_PORT=192.168.130.10:4731`)
* set the encryption key (default: `sakuli_secret`; overwrite with e.g. `export GEARMAN_SECRET=mykey`)

[source]
----
OMD[demo]:~/share/sakuli/setup$ make gearman [enter]
...
----

NOTE: For security reasons, the Makefile will only configure mod-gearman if it is not enabled yet. If it is already enabled, inspect the Makefile, read the steps carefully and execute the steps by hand.

IMPORTANT: For PRODUCTION usage please use individual encryption key!

By default, mod_gearman does only accept AES encrypted packages. Since version `1.1.0` Sakuli will automatic use the encryption key `sakuli_secret` (located at the `<<sakuli-default-properties,sakuli-default.properties>>`). To change the encryption password, see <<sakuli_gearman_client_config>>.

If you do not want to use encryption at all enable `accept_clear_results` and disable `sakuli.forwarder.gearman.encryption`:

[source,bash]
----
OMD[demo]:~ vim ~/etc/mod-gearman/server.cfg
...
accept_clear_results=yes
----
[source, properties]
----
#testsuite.properties
sakuli.forwarder.gearman.encryption=false
----


====== Create a Nagios service

Create a service which should receive Sakuli test results. Host/service names derive from the following <<property-loading-mechanism,properties>>:

* *host*: `sakuli.forwarder.gearman.nagios.hostname` (defined globally or per suite)
* *service*: `testsuite.id` (defined in `testsuite.properties`)

[source]
----
define host {
  host_name                      sakuli_client
  alias                          sakuli_client
  address                        __SAKULI_CLIENT_IP__
  use                            generic-host
}

define service {
  service_description            example_xfce
  host_name                      sakuli_client
  use                            tpl_s_sakuli_gearman
  freshness_threshold            180
}
----

[[omd-gearman-freshness_threshold]]
TIP: _freshness_threshold_ should be slightly higher than the interval Sakuli tests are executed

The check is waiting now for check results from a Sakuli client.

[[sakuli_gearman_client_config]]
===== Sakuli Client Configuration

.Modify Sakuli gearman forwarder parameter

On the Sakuli client you must set the global <<property-loading-mechanism,properties>> for the gearman receiver. For this, edit `sakuli.properties` in the folder containing the test suites (you can copy the lines from `__SAKULI_HOME__/conf/sakuli-default.properties`):.

[source,properties]
----
__INST_DIR__/example_test_suites/sakuli.properties:

sakuli.forwarder.gearman.enabled=true
sakuli.forwarder.gearman.encryption=true <1>
sakuli.forwarder.gearman.secret.key=secret_password <1>
sakuli.forwarder.gearman.server.host=__GEARMAN_IP__
sakuli.forwarder.gearman.server.port=[Gearman Port defined in "omd config" (default:4730)]
sakuli.forwarder.gearman.server.queue=check_results <2>

# Nagios host where all Sakuli services are defined on. If neccessary, override this value per test suite.
# (Nagios service name is defined by testsuite.properties -> suiteID)
sakuli.forwarder.gearman.nagios.hostname=sakuli_client
sakuli.forwarder.gearman.nagios.check_command=check_sakuli
----

<1> Enable encryption and set the key only if you did not activate `accept_clear_results` in mod_gearman. Otherwise, set encryption to `false`.
<2> Change this queue name if you use the <<gearman_proxy,Sakuli Gearman proxy>>

In case you get a `java.lang.security.InvalidKeyException` with error message _"Illegal key size or default parameters"_ you probably
need to enable unlimited strength security policies in your Java JRE. This is done by adding a special security policy JAR to the Java JRE lib directory. For the Java JRE 8, take a look at http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html[Oracle - Java Cryptography Extension 8].

[[gearman_proxy]]
===== Gearman proxy (optional)

image:gearman_proxy.png[gearman_proxy,780]

Use the Sakuli gearman proxy script if you want to intervene into the communication between Sakuli and Naemon/Nagios.

*Possible use cases*:

* Change parts of the messages Sakuki sends to the monitoring system => there are some examples contained already
* Getting notified when Sakuli sends results to services which do not exists
* Auto-create services for incoming results (not yet implemented)

Use the Makefile located in `$OMD_ROOT/share/sakuli/` to enable the feature:

[source]
----<commit_msg>#91 add usage of OpenJDK in case of `InvalidKeyException` to gearman encryption documentation<commit_after>
:imagesdir: ../../../images

[[omd-gearman]]
==== Gearman forwarder
[#git-edit-section]
:page-path: docs/manual/integration/monitoring/omd-gearman.adoc
git-link:{page-path}{git-view} | git-link:{page-path}{git-edit}

This page describes how the results of Sakuli tests can be transmitted directly into the *Gearman result queue* of a monitoring system.

NOTE: If you do not use a gearman-enabled monitoring system in a https://labs.consol.de/OMD/[OMD] environment, the procedure may vary.

image:sakuli-gearman.png[sakuli-db-forwarder]


===== OMD Configuration

====== Enable and configure mod-gearman

Use the Makefile located in `$OMD_ROOT/share/sakuli/` to configure mod_gearman:

* enable all services for mod_gearman
* set the bind IP and port (default: `0.0.0.0:4730`; overwrite with e.g. `export GEARMAND_PORT=192.168.130.10:4731`)
* set the encryption key (default: `sakuli_secret`; overwrite with e.g. `export GEARMAN_SECRET=mykey`)

[source]
----
OMD[demo]:~/share/sakuli/setup$ make gearman [enter]
...
----

NOTE: For security reasons, the Makefile will only configure mod-gearman if it is not enabled yet. If it is already enabled, inspect the Makefile, read the steps carefully and execute the steps by hand.

IMPORTANT: For PRODUCTION usage please use individual encryption key!

By default, mod_gearman does only accept AES encrypted packages. Since version `1.1.0` Sakuli will automatic use the encryption key `sakuli_secret` (located at the `<<sakuli-default-properties,sakuli-default.properties>>`). To change the encryption password, see <<sakuli_gearman_client_config>>.

If you do not want to use encryption at all enable `accept_clear_results` and disable `sakuli.forwarder.gearman.encryption`:

[source,bash]
----
OMD[demo]:~ vim ~/etc/mod-gearman/server.cfg
...
accept_clear_results=yes
----
[source, properties]
----
#testsuite.properties
sakuli.forwarder.gearman.encryption=false
----


====== Create a Nagios service

Create a service which should receive Sakuli test results. Host/service names derive from the following <<property-loading-mechanism,properties>>:

* *host*: `sakuli.forwarder.gearman.nagios.hostname` (defined globally or per suite)
* *service*: `testsuite.id` (defined in `testsuite.properties`)

[source]
----
define host {
  host_name                      sakuli_client
  alias                          sakuli_client
  address                        __SAKULI_CLIENT_IP__
  use                            generic-host
}

define service {
  service_description            example_xfce
  host_name                      sakuli_client
  use                            tpl_s_sakuli_gearman
  freshness_threshold            180
}
----

[[omd-gearman-freshness_threshold]]
TIP: _freshness_threshold_ should be slightly higher than the interval Sakuli tests are executed

The check is waiting now for check results from a Sakuli client.

[[sakuli_gearman_client_config]]
===== Sakuli Client Configuration

.Modify Sakuli gearman forwarder parameter

On the Sakuli client you must set the global <<property-loading-mechanism,properties>> for the gearman receiver. For this, edit `sakuli.properties` in the folder containing the test suites (you can copy the lines from `__SAKULI_HOME__/conf/sakuli-default.properties`):.

[source,properties]
----
__INST_DIR__/example_test_suites/sakuli.properties:

sakuli.forwarder.gearman.enabled=true
sakuli.forwarder.gearman.encryption=true <1>
sakuli.forwarder.gearman.secret.key=<PASSWORD>_password <1>
sakuli.forwarder.gearman.server.host=__GEARMAN_IP__
sakuli.forwarder.gearman.server.port=[Gearman Port defined in "omd config" (default:4730)]
sakuli.forwarder.gearman.server.queue=check_results <2>

# Nagios host where all Sakuli services are defined on. If neccessary, override this value per test suite.
# (Nagios service name is defined by testsuite.properties -> suiteID)
sakuli.forwarder.gearman.nagios.hostname=sakuli_client
sakuli.forwarder.gearman.nagios.check_command=check_sakuli
----

<1> Enable encryption and set the key only if you did not activate `accept_clear_results` in mod_gearman. Otherwise, set encryption to `false`.
<2> Change this queue name if you use the <<gearman_proxy,Sakuli Gearman proxy>>

[[invalid-key-exception-aes-cryptography]]
TIP: In case you get a `java.lang.security.InvalidKeyException` with error message _"Illegal key size or default parameters"_ you probably
need to enable unlimited strength security policies in your Java JRE. This is done by installing http://openjdk.java.net/[OpenJDK] or by adding a special security policy JAR to the Java JRE lib directory. For the Java JRE 8, take a look at http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html[Oracle - Java Cryptography Extension 8].

[[gearman_proxy]]
===== Gearman proxy (optional)

image:gearman_proxy.png[gearman_proxy,780]

Use the Sakuli gearman proxy script if you want to intervene into the communication between Sakuli and Naemon/Nagios.

*Possible use cases*:

* Change parts of the messages Sakuki sends to the monitoring system => there are some examples contained already
* Getting notified when Sakuli sends results to services which do not exists
* Auto-create services for incoming results (not yet implemented)

Use the Makefile located in `$OMD_ROOT/share/sakuli/` to enable the feature:

[source]
----
{'fraction_non_alphanumeric': 0.09449995331029974, 'fraction_numerical': 0.009711457652441871, 'mean_word_length': 4.270669291338582, 'pattern_counts': {'":': 0, '<': 34, '<?xml version=': 0, '>': 38, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '973729', 'n_tokens_mistral': 3368, 'n_tokens_neox': 3178, 'n_words': 1074}