# Monitoring ## Host Check Command The module provides a CLI command to check a host's certificate. It does so by fetching all the necessary information from this module's own database. ### Usage General: `icingacli x509 check host [options]` Options: ``` --ip A hosts IP address --host A hosts name --port The port to check in particular --warning Less remaining time results in state WARNING [25%] --critical Less remaining time results in state CRITICAL [10%] --allow-self-signed Ignore if a certificate or its issuer has been self-signed ``` ### Threshold Definition Thresholds can either be defined relative (in percent) or absolute (time interval). Time intervals consist of a digit and an accompanying unit (e.g. "3M" are three months). Supported units are: Identifier | Description ------------|------------ y, Y | Year M | Month d, D | Day h, H | Hour m | Minute s, S | Second **Example:** ``` $ icingacli x509 check host --host example.org --warning 1y WARNING - *.example.org expires in 219 days|'*.example.org'=18985010s;25574400;10281600;0;102470399 ``` ### Performance Data The command outputs a performance data value for each certificate that is served by the host. The value measured is the amount of seconds remaining until the certificate expires. ![check host perf data](res/check-host-perf-data.png) The value of `max` is the total amount of seconds the certificate is valid. `warning` and `critical` are the seconds remaining after which the respective state is reported. ## Icinga 2 Integration First off, this chapter relies on the fact that you're using the Director already and that you're familiar with some of the terms and functionalities used there. If you don't want to use the Director, know that Icinga 2 already provides an appropriate template for the host check command in its template library: https://icinga.com/docs/icinga2/latest/doc/10-icinga-template-library/#x509 ### Director Import Sources The module provides two different import sources: #### Hosts (X509) Focuses on the hosts the module found when scanning the networks. Use this for the most straightforward way of integrating the results into your environment. It's also the utilized source in the example further below. Columns provided by this source: Name | Description ----------------|-------------------------------------------------------------- host_name_or_ip | Default key column. This is primarily `host_name`, though if this is not unique it falls back to `host_ip` for individual results host_ip | A host's IP address by which it is known to this module. May be IPv4 or IPv6 host_name | A host's name as detected by SNI or a reverse DNS lookup during the scan process host_ports | Separated by comma. All ports where certificates were found host_address | Set to `host_ip` if it is IPv4 else `null` host_address6 | Set to `host_ip` if it is IPv6 else `null` #### Services (X509) While the hosts import source does not provide any details about the found certificates this one does. This also means that this source may generate multiple results for a single host since it focuses on the found certificates. Use this source if you want to import service objects directly and relate them to already existing hosts by their utilized certificates. The Director's many utilities provided in this regard will again come in handy here. Columns provided by this source: Name | Description ----------------------|-------------------------------------------------------- host_name_ip_and_port | Default key column. This is a combination of `host_name`, `host_ip` and `host_port` in the format `name/ip:port` host_ip | A host's IP address by which it is known to this module. May be IPv4 or IPv6 host_name | A host's name as detected by SNI or a reverse DNS lookup during the scan process host_port | A host's port where a certificate has been found host_address | Set to `host_ip` if it is IPv4 else `null` host_address6 | Set to `host_ip` if it is IPv6 else `null` cert_subject | A certificate's common name cert_issuer | The issuer's common name cert_self_signed | Whether the certificate is self-signed (`y` or `n`) cert_trusted | Whether the certificate is trusted (`y` or `n`) cert_valid_from | The certificate's start time of validity (UNIX timestamp) cert_valid_to | The certificate's end time of validity (UNIX timestamp) cert_fingerprint | The certificate's fingerprint (hex-encoded) cert_dn | The certificate's distinguished name cert_subject_alt_name | The certificate's alternative subject names (Comma separated pairs of `type:name`) ### Service Checks With the Hosts Import Source This example covers the setup of service checks by using a particular host template and suggests then two options utilizing service apply rules. #### Preparations Assuming the check command definition `icingacli-x509` has already been imported you need to define a few data fields now: Field name | Data type ---------------------------------|---------- certified_ports | Array icingacli_x509_ip | String icingacli_x509_host | String icingacli_x509_port | String icingacli_x509_warning | String icingacli_x509_critical | String icingacli_x509_allow_self_signed | Boolean Then please create a new host template with a name of your choosing. We've chosen `x509-host`. We're also importing our base template `base-host` here which defines all the default properties of our hosts. ![new host template](res/new-host-template.png) This host template also requires three data fields which are shown below. ![host template fields](res/host-template-fields.png) A service template is also needed. We chose the name `x509-host-check` and `icingacli-x509` as check command. ![new service template](res/new-service-template.png) The service template now requires all data fields which correspond to the check command's parameters. ![service template fields](res/service-template-fields.png) #### Import Source Setup Create a new import source of type `Hosts (X509)`. ![hosts import source](res/hosts-import-source.png) Configure a property modifier for column `host_ports` of type `Split` and use the comma `,` as delimiter. ![ports property modifier](res/ports-property-modifier.png) The preview should now produce a similar result to this: ![hosts import result](res/hosts-import-result.png) #### Sync Rule Setup Create a new sync rule for objects of type `Host`. Depending on your environment you may choose either `Merge` or `Replace` as update policy. Choose `Merge` to continue with this example. Which properties this rule defines is also very dependent on what you want to achieve. We now assume that you already have host objects whose object names match exactly those the import source provides. (Hence you should choose `Merge` as update policy) ![sync rule properties](res/sync-rule-properties.png) #### Service Check Setup There are two choices now. The first checks a host's certificates as a single service. The second creates for each individual certificate (port) a service. ##### Single Service This is done by defining a new service as part of the host template created earlier. There add a service and choose the service template also created previously. ![host check single service](res/host-check-single-service.png) Once you've triggered the import and synchronisation as well as deployed the resulting changes you should see this in Icinga Web 2: ![single service result](res/single-service-result.png) ##### Multiple Services This utilizes a service apply rule. Trigger the import and synchronisation first, otherwise you can't choose a custom variable for the *apply for* rule. Once the synchronisation is finished, set up the service apply rule like this: ![host check multiple services](res/host-check-multiple-services.png) After deploying the resulting changes you should see this in Icinga Web 2: ![multiple services result](res/multiple-services-result.png)