diff --git a/doc/features/feature-api.md b/doc/features/feature-api.md index c53307cd..59b5c2bb 100644 --- a/doc/features/feature-api.md +++ b/doc/features/feature-api.md @@ -74,8 +74,8 @@ icinga2_features: - name: api cert_name: host.example.org ssl_ca: /home/ansible/certs/ca.crt - ssl_cert:/home/ansible/certs/host.crt - ssl_key:/home/ansible/certs/host.key + ssl_cert: /home/ansible/certs/host.crt + ssl_key: /home/ansible/certs/host.key endpoints: - name: NodeName zones: @@ -83,3 +83,36 @@ icinga2_features: endpoints: - NodeName ``` + +### Feature variables + +* `icinga2_ca_host: string` + * Use to point the Icinga 2 installation to where to get the certificates. When set to **None**, Ansible will create a local Certificate Authority on the Host. Use **hostname** or **ipaddress** as value. + +* `force_newcert: boolean` + * Force new certificates on the destination hosts. + +* `cert_name: string` + * Common name of Icinga client/server instance. Default is **ansible_fqdn**. + +* `ssl_ca: string` + * Path to the ca file when using manual certificates + +* `ssl_cert: string` + * Path to the certificate file when using manual certificates. + +* `ssl_key: string` + * Path to the certificate key file when using manual certificates. + +* `endpoints: list of dicts` + * Defines endpoints in **zones.conf**, each endpoint is required to have a name and optional a host or port. + * `name: string` + * `host: string` + * `port: number` + +* `zones: list of dicts` + * Defines zones in **zones.conf**, each zones is required to have a name and endpoints. The parameter global is optional. + * `name: string` + * `endpoints: list` + * `global: boolean` + diff --git a/doc/features/feature-graphite.md b/doc/features/feature-graphite.md new file mode 100644 index 00000000..3f28bbd5 --- /dev/null +++ b/doc/features/feature-graphite.md @@ -0,0 +1,18 @@ +## Graphite + +To enable the feature Graphite use the following block in the variable `icinga2_features`. + +``` +icinga2_features: + - name: graphite + host: localhost + port: 2003 +``` + +### Feature variables + +* `host: string` + * Name or address of the graphite instance. + +* `port: int` + * diff --git a/doc/features/feature-ido.md b/doc/features/feature-ido.md index 97e52826..c1eab318 100644 --- a/doc/features/feature-ido.md +++ b/doc/features/feature-ido.md @@ -41,4 +41,73 @@ icinga2_features: cleanup: downtimehistory: 48h contactnotifications_age: 31d -``` +``` + +### Feature variables + +* `host: string` + * MySQL/PgSQL database host address. Default **localhost**. + +* `port: int` + * Database port. Defaults to **3306** for MySQL and **5432** for PgSQL. + +* `database: string` + * Database name. Defaults to **icinga2**. + +* `user: sring` + * Database user with read/write permission to the icinga database. Defaults to **icinga2**. + +* `password: string` + * Database user’s password. + +* `state: string` + * Decides whether the feature is enabled or disabled. Possible values present, absent. + +* `enable_ssl: boolean` + * Use SSL. Change to true in case you want to use any of the SSL options. + +* `ssl_mode: string` + * **Only PgSQL**: nable SSL connection mode. Value must be set according to the sslmode setting: prefer, require, verify-ca, verify-full, allow, disable. + +* `ssl_key: string` + * SSL client key file path. + +* `ssl_cert: string` + * SSL certificate file path. + +* `ssl_ca: string` + * SSL certificate authority certificate file path. + +* `ssl_capath: string` + * SSL trusted SSL CA certificates in PEM format directory path. + +* `ssl_cipher: string` + * **Only MySQL**: SSL list of allowed ciphers. + +* `socket_path: string` + * **Only MySQL**: MySQL socket path. + +* `table_prefix: string` + * Database table prefix. + +* `instance_name: string` + * Unique identifier for the local Icinga 2 instance, used for multiple Icinga 2 clusters writing to the same database. Defaults to default. + +* `instance_description: string` + * Description for the Icinga 2 instance. + +* `enable_ha: boolean` + * Enable the high availability functionality. Only valid in a cluster setup. + +* `failover_timeout: string` + * Set the failover timeout in a HA cluster. Must not be lower than 30s. Defaults to 30s + +* `cleanup: dict` + * Dictionary with items for historical table cleanup. + +* `categories: list` + * Array of information types that should be written to the database. + +* `import_schema: boolean` + * Import schema in the database set for the feature. + diff --git a/doc/features/feature-mainlog.md b/doc/features/feature-mainlog.md new file mode 100644 index 00000000..8775b6db --- /dev/null +++ b/doc/features/feature-mainlog.md @@ -0,0 +1,19 @@ +## Mainlog + +To enable the feature mainlog add the following block to the variable `icinga2_features`. + +``` +icinga2_features: + - name: mainlog +``` + +### Feature variables + +* `severity: string` + * The minimum severity for this log. Possible values “debug”, “notice”, “information”, “warning” or “critical”. + +* `path: string` + * The Log Path, default: `LogDir + /icinga2.log` + +* `state: string` + * Decides whether the feature is enabled or disabled. Possible values present, absent. \ No newline at end of file diff --git a/doc/features/feature-notification.md b/doc/features/feature-notification.md new file mode 100644 index 00000000..f9010d8e --- /dev/null +++ b/doc/features/feature-notification.md @@ -0,0 +1,32 @@ +## Notification + +To activate the feature notification add this block to the variable `icinga2_features`. + +``` +icinga2_features: + - name: notification +``` + +### Notification Scripts + +The role won't manage notifications scripts with the role. Many scripts require dependencies or libraries to be installed. To manage those dependencies create a Ansible role and use it after the Icinga 2 role. + +If there are no dependencies on the script you can easily use the `post_tasks` section in your playbook. Example: + +``` +post_tasks: + - name: copy notifications script + src: rocket_chat_notification.py + dest: /etc/icinga2/scripts/rocket_chat_notification.py + group: "{{ icinga2_group }} + user: "{{ icinga2_user}}" +``` + +### Feature Attributes + +* `enable_ha: boolean` + * Enable the high availability functionality. Only valid in a cluster setup. Disabling this currently only affects reminder notifications. + +* `state: string` + * Decides whether the feature is enabled or disabled. Possible values present, absent. + diff --git a/doc/objects.md b/doc/objects.md index bd1630f5..15f95ab4 100644 --- a/doc/objects.md +++ b/doc/objects.md @@ -53,9 +53,10 @@ icinga2_objects: ``` -#### Object Service +#### Service Apply ``` +icinga2_objects: [...] - name: ping type: Service @@ -69,19 +70,65 @@ icinga2_objects: - host.address ``` +### Service Object + +``` +icinga2_objects: +[...] + - name: ping6 + type: Service + file: zones.d/main/agent.localdomain.conf + imports: + - generic-service + check_command: ping6 + host_name: agent.localdomain +``` + ### Service Group ``` icinga2_objects: [...] - - name: service_group_linux - type: ServiceGroup - file: "local.d/groups.conf" - display_name: Linux Services - assign: - - host.vars.os == linux + - name: service_group_linux + type: ServiceGroup + file: "local.d/groups.conf" + display_name: Linux Services + assign: + - host.vars.os == linux +``` + +### ApiUser + +``` +icinga2_objects: +[...] + - name: icinga-api + type: ApiUser + file: "local.d/apiuser.conf" + password: supersecrectpassword123 + permissions: + - "objects/query/Host" + - "objects/query/Service" + ``` +### TimePeriod + +``` +icinga2_objects: +[...] +- name: 24x7 + type: TimePeriod + file: "local.d/timeperiods.conf" + ranges: + monday: "00:00-24:00" + tuesday: "00:00-24:00" + wednesday: "00:00-24:00" + thursday: "00:00-24:00" + friday: "00:00-24:00" +``` + + ## Managing Config directories To create or prepare the directories for the monitoring configuration use the variable `icinga2_config_directories`. @@ -93,3 +140,153 @@ icinga2_config_directories: - zones.d/main/services/ - conf.d/commands/ ``` + +## Parser Rules + +The collection provides the possibility to deploy Icinga 2 configuration, this includes configuration to shape the instance and monitoring data to create a complete monitoring environment. + +### Basic Syntax + +The parser takes every value in the configuration and decides how the value should be written in the configuration. This takes a few rules to handle the configuration the right way. + +First of all, to disable the parser use the prefix `-:`. + +``` +attr: -:"unparsed quoted string" +``` + +Strings are parsed in chunks, by splitting the original string into separate substrings at specific keywords (operators) such as `+`, `-`, `in`, `&&`, `||`, etc. + +**NOTICE:** This splitting only works for keywords that are surrounded by whitespace, e.g.: + +``` +attr: string1 + string2 - string3 +``` + +The algorithm will loop over the parameter and start by splitting it into 'string1' and 'string2 - string3'. 'string1' will be passed to the sub function 'value_types' and then the algorithm will continue parsing the rest of the string ('string2 - string3'), splitting it, passing it to value_types, etc. + +Brackets are parsed for expressions: + +``` +attr: 3 * (value1 - value2) / 2 +``` + +The parser also detects function calls and will parse all parameters separately. + +``` +attr: function(param1, param2, ...) +``` + +Boolean values can be defined with or without quotes. In addition the Ansible bool types `yes` or `no` can be used either. + +``` +attr: true or attr: 'true' +``` + +To avoid overlapping syntax with Ansible variable syntax, please refer to single quotes `' '` when using own lambda functions in Icinga. + +``` +attrs => '{{ ... }}' +``` + +In general all values can be defined without quotes except for lamba functions where Ansible's own syntax would interfere with the double brackets. + +| Type | Examples | +|----------------|------------------------------------------| +| Boolean | `true`,`false`,`True`,`False`,`yes`,`no` | +| Numbers | `2` or `3.5` | +| Time Intervals | `3m` or `3.5h` | +| String | `attr: string` | + +### Advanced Syntax + +To replicate Icinga 2 advanced syntax like assignments with `+=` or `-=` you can use the prefix `+` or `-`. + +To create the following Icinga 2 DSL syntax, +``` +var += config +``` +simply use a string with the prefix `+` e.g. + +``` +var: `+ config` +``` + +Because of the blank between the `+` and `config` those values are separately parsed and therefore numbers are also possible. For numbers we also can build `-=`, just use the minus sign `-`. This method will work for every attribute or custom attribute. + +``` +attr: + -14 or attr: - -14 +``` + +The parser is able to merge or reduce an array. For this method set the first item of your array as `+` or `-` sign. + +``` +attr: + - + + - item1 + - item2 + +# Alterntive syntax +attr: ['-','item1','item2'] +``` +Result in Icinga will be `attr += [ "item1", "item2", ]`. + +To reduce arrays use the minus sign `-`. + +**NOTICE** Please be aware that the minus sign needs to be quoted otherwise the Ansible parser will have troubles reading the array. + +``` +attr: + - '-' + - item1 + - item2 + +# Alterntive syntax +attr: ['-','item1','item2'] +``` + +Result in Icinga will be `attr -= [ "item1", "item2", ]`. + +#### Dictionaries + +To merge dictionaries we can use the plus sign `+`. The plus sign needs to be a key in the dictionary. See following example. + +``` +attr: + +: true + key1: value1 +``` + +The result: + +``` +attr["key1"] = "value1" +``` + +The useage of levels in dictionaries aren't limited. + +``` +attr: + key1: + key2: + key3: + +: true + value: test +``` + +Result: + +``` +vars.attr["key1"] = { + key2 = { + key3 += { + value = "test" + } + } + } +``` + + + + + diff --git a/doc/role-icinga2.md b/doc/role-icinga2.md index 93e94bee..80a7450b 100644 --- a/doc/role-icinga2.md +++ b/doc/role-icinga2.md @@ -4,7 +4,19 @@ The collection provides several roles to install and configure Icinga 2. This ## Variables -### Mange Configuration +* `icinga2_purge_features: boolean` + * Decides whether the unmanaged features should be purged or not. Default: true + +* `icinga2_constants: dict` + * Define constants in **constants.conf**, for defaults check the vars folder. + +``` +icinga2_constants: + NodeName: satellite.localdomain + ZoneName: zone-satellite-d1 +``` + +### Manage Configuration If the local **conf.d** directory shouldn't be recursively included then the var `icinga2_confd` should be set to `false`. @@ -12,9 +24,17 @@ var `icinga2_confd` should be set to `false`. Otherwise you can use a directory name to set the include to a different folder than **conf.d**. The folder needs to exist below /etc/icinga2. If it should be created by the role use the variable `icinga2_config_directories` in addition. - - ``` icinga2_confd: true/false/ +``` + +### SELinux handling + +The Icinga 2 role will automatically detect via Ansible facts if SELinux is enabled on the system. If this is the case the package icinga2-selinux will be automatically installed. + +If the package should be installed, even if SELinux is not enabled or somehow wrongly disabled in Ansible use the following variable. ``` +ansible_selinux: + status: enabled +``` \ No newline at end of file