Skip to content

Ansible Role linuxfabrik.lfops.icinga2_agent

This role installs Icinga2, configures it to act as an agent, and tries to registers the host in the Icinga Director.

Currently, this role only works if the host can reach the Icinga2 master API.

Available since LFOps 2.0.0.

How the Role Behaves

  • The agent certificate is signed by the Icinga2 master. The role requests a ticket for the agent's CN from the master API (icinga2_agent__icinga2_api_user_login) and passes it to icinga2 node setup, so the master signs the certificate right away (CSR auto-signing).
  • icinga2 node setup (tags icinga2_agent and icinga2_agent:node_setup) creates a new key and certificate for the agent each time it runs, so the role only runs it, requests a ticket for it and restarts the agent when one of these applies: the agent certificate is missing, expired or not signed by the CA of the master, the master presents a different certificate than before (for example after it was rebuilt), or one of the icinga2_agent__* settings passed to icinga2 node setup changed. A hash of these settings is kept in /var/lib/icinga2/linuxfabrik-node-setup.sha256; delete the file to force a new node setup.
  • If the role cannot get a ticket, the run aborts before icinga2 node setup and says why, since without one the agent would be left with an unsigned certificate, even if it was connected before.
  • If the master does not accept a connection on icinga2_agent__icinga2_master_host and icinga2_agent__icinga2_master_port from this host within 10 seconds, the run aborts before the node setup and names the address it tried.
  • With icinga2_agent__skip_pki_ticket: true, the role requests no ticket and sets the agent up without one. Its certificate request then has to be signed on the master by hand (on-demand CSR signing). Until it is signed, every run creates a new request.

Dependent Roles

Any LFOps playbook that installs this role runs these for you. Optional ones can be disabled via the playbook's skip variables.

Requirements

Manual steps:

Tags

icinga2_agent

  • Installs and configures icinga2 as an agent.
  • Triggers: icinga2.service restart.

icinga2_agent:logrotate

icinga2_agent:node_setup

  • Runs the icinga2 node setup if the agent needs it (see "How the Role Behaves") and registers the host in the Director.
  • Triggers: icinga2.service restart, if the node setup ran.

icinga2_agent:state

  • Manages the state of the Icinga2 service.
  • Triggers: none.

icinga2_agent:systemd_override

  • Deploys: /etc/systemd/system/icinga2.service.d/z00-after-sssd.conf.
  • Triggers: none.

icinga2_agent:update

  • Updates the Icinga2 package and restarts the service.
  • Triggers: icinga2.service restart.

Mandatory Role Variables

icinga2_agent__icinga2_api_user_login

  • The account for generating a ticket for this agent using the Icinga2 API (API of Icinga Core). The account needs to have the actions/generate-ticket permission on the Icinga2 Master. Not used if icinga2_agent__skip_pki_ticket is true.
  • Type: Dictionary.

icinga2_agent__icinga2_master_cn

  • The common name of the Icinga2 Master.
  • Type: String.

icinga2_agent__windows_version

Example:

icinga2_agent__icinga2_api_user_login:
  password: 'password'
  username: 'enrolment-user'
icinga2_agent__icinga2_master_cn: 'master.example.com'
icinga2_agent__windows_version: 'v2.12.8'

Optional Role Variables

icinga2_agent__additional_icinga2_master_endpoints

  • A list of dictionaries with additional Icinga2 master endpoints.
  • Type: List of dictionaries.

  • Default: []

  • Subkeys:

    • host:

      • Mandatory. Host of the master endpoint.
      • Type: String.

    • port:

      • Optional. The Icinga2 port of the endpoint.
      • Type: Number.
      • Default: 5665

icinga2_agent__bind_host

  • The bind host. This allows restricting on which IP addresses the Agent is listening.
  • Type: String.
  • Default: unset

icinga2_agent__cn

  • The common name of the Icinga2 Agent. Tries to default to the FQDN of the server.
  • Type: String.
  • Default: '{{ ansible_facts["nodename"] }}'

icinga2_agent__director_host_object_address

  • The host address of the Icinga Director host object. Tries to default to the IPv4 address of the server.
  • Type: String.
  • Default: '{{ ansible_facts["ip_addresses"][0] }}' for Windows, else '{{ ansible_facts["default_ipv4"]["address"] }}'

icinga2_agent__director_host_object_display_name

  • The host display name of the Icinga Director host object. Tries to default to the hostname.
  • Type: String.
  • Default: '{{ ansible_facts["hostname"] }}'

icinga2_agent__director_host_object_import

  • A list of Icinga Director host templates which should be imported for this server.
  • Type: List of strings.
  • Default: ['tpl-host-windows'] for Windows, else ['tpl-host-linux']

icinga2_agent__icinga2_api_url

  • The URL to the Icinga2 API. Will be used to generate the ticket for the agent certificate.
  • Type: String.
  • Default: 'https://{{ icinga2_agent__icinga2_master_host }}:{{ icinga2_agent__icinga2_master_port }}'

icinga2_agent__icinga2_master_host

  • The host where the Icinga2 Master is running. Has to be reachable from the Agent.
  • Type: String.
  • Default: '{{ icinga2_agent__icinga2_master_cn }}'

icinga2_agent__icinga2_master_port

  • The port on which the Icinga2 master is reachable.
  • Type: Number.
  • Default: 5665

icinga2_agent__icingaweb2_url

  • The URL where the IcingaWeb2 (the API) is reachable. This will be used to register the host in the Icinga Director (otherwise the host is registered in Icinga Core, but not visible in Icinga Director).
  • Type: String.
  • Default: 'https://{{ icinga2_agent__icinga2_master_host }}/icingaweb2'

icinga2_agent__icingaweb2_user_login

  • A IcingaWeb2 user with module/director,director/api,director/hosts permissions. This will be used to register the host in the Icinga Director.
  • Type: Dictionary.
  • Default: unset

icinga2_agent__parent_zone

  • The Icinga2 parent zone of the host.
  • Type: String.
  • Default: 'master'

icinga2_agent__service_enabled

  • Enables or disables the Icinga2 service, analogous to systemctl enable/disable --now.
  • Type: Bool.
  • Default: true

icinga2_agent__skip_pki_ticket

  • Do not request a ticket from the Icinga2 master, and set the agent up without one. The certificate request of the agent then has to be signed on the master by hand, after every run of the role. See "How the Role Behaves".
  • Type: Bool.
  • Default: false

icinga2_agent__validate_certs

  • If false, TLS certificates offered by the Icinga Master will not be validated. This should only set to false used on personally controlled sites using self-signed certificates.
  • Type: Bool.
  • Default: true

icinga2_agent__windows_download_path

  • The path where the Icinga2.exe will be downloaded to. Certain Windows versions disallow the creation of files in C: which requires one to adjust this setting. Note that the path has to exist.
  • Type: String.
  • Default: 'C:'

icinga2_agent__windows_service_user

  • The Windows user account under which the Icinga2 service will be run.
  • Type: String.
  • Default: 'NT AUTHORITY\SYSTEM'

icinga2_agent__zone

  • The zone of the agent (endpoint). Change this if you are installing a satellite.
  • Type: String.
  • Default: '{{ icinga2_agent__cn }}'

Example:

# optional
icinga2_agent__additional_icinga2_master_endpoints:
  - host: 'master2.example.com'
    port: 5665
  - host: 'master3.example.com'
icinga2_agent__bind_host: '0.0.0.0'
icinga2_agent__cn: '{{ ansible_facts["nodename"] }}'
icinga2_agent__director_host_object_address: '{{ ansible_facts["default_ipv4"]["address"] }}'
icinga2_agent__director_host_object_display_name: '{{ ansible_facts["hostname"] }}'
icinga2_agent__director_host_object_import:
  - 'tpl-host-linux'
icinga2_agent__icinga2_api_url: 'https://master3.example.com:{{ icinga2_agent__icinga2_master_port }}'
icinga2_agent__icinga2_master_host: '192.0.2.10'
icinga2_agent__icinga2_master_port: 5665
icinga2_agent__icingaweb2_url: 'https://monitoring.example.com/icingaweb2'
icinga2_agent__icingaweb2_user_login:
  password: 'password'
  username: 'enrolment-user'
icinga2_agent__parent_zone: 'satellite01'
icinga2_agent__service_enabled: true
icinga2_agent__skip_pki_ticket: false
icinga2_agent__validate_certs: true
icinga2_agent__windows_download_path: 'D:\Downloads'
icinga2_agent__windows_service_user: 'Icinga Service User'
icinga2_agent__zone: 'satellite'

Troubleshooting

The run aborts with icinga2_agent: Could not get a PKI ticket from ...

  • The message contains the answer of the Icinga2 master API. Fix the cause and run the role again:

    • Status code was 401: The username or password in icinga2_agent__icinga2_api_user_login is wrong.
    • Status code was 404: The API user lacks the actions/generate-ticket permission on the master; Icinga2 answers 404 instead of 403 in this case. Also check that icinga2_agent__icinga2_api_url points to the Icinga2 API (port 5665 by default), not to IcingaWeb2.
    • Status code was 500: Check the log of the Icinga2 master. It answers 500 for example if its TicketSalt constant is not set.
    • Status code was -1: The master API did not answer at all. Check that icinga2_agent__icinga2_api_url is reachable from the agent (DNS, firewall).

  • To sign the agent certificate on the master by hand instead, set icinga2_agent__skip_pki_ticket: true (see "How the Role Behaves").

The run aborts with icinga2_agent: icinga2_agent__icinga2_api_user_login is not set

  • Set icinga2_agent__icinga2_api_user_login, or set icinga2_agent__skip_pki_ticket: true to sign the agent certificate on the master by hand.

icinga2_agent: The agent requested its certificate without a ticket

  • icinga2_agent__skip_pki_ticket is true. On the Icinga2 master, run icinga2 ca list, and sign the newest request for the agent's CN with icinga2 ca sign <fingerprint>.

License

The Unlicense

Author Information

Linuxfabrik GmbH, Zurich