# icinga2_host – Manage a host in Icinga2

New in version 2.5.

- Synopsis
- Parameters
- Examples
- Return Values
- Status

## Synopsis

- Add or remove a host to Icinga2 through the API.
- See https://www.icinga.com/docs/icinga2/latest/doc/12-icinga2-api/

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
check_command - | Default: "hostalive" | The command used to check if the host is alive.
client_cert - |  | PEM formatted certificate chain file to be used for SSL client authentication. This file can also include the key as well, and if the key is included, `client_key` is not required.
client_key - |  | PEM formatted file that contains your private key to be used for SSL client authentication. If `client_cert` contains both the certificate and key, this option is not required.
display_name - | Default: "if none is give it is the value of the \u003cname\u003e parameter" | The name used to display the host.

force_basic_auth
boolean

Choices:
- no ←
- yes

httplib2, the library used by the uri module only sends authentication information when a webservice responds to an initial request with a 401 status. Since some basic auth services do not properly send a 401, logins will fail. This option forces the sending of the Basic authentication header upon initial request.

ip - / required |  | The IP address of the host.
name - / required |  | Name used to create / delete the host. This does not need to be the FQDN, but does needs to be unique.

state
-

Choices:
- present ←
- absent

Apply feature state.

template - |  | The template used to define the host. Template cannot be modified after object creation.
url - / required |  | HTTP, HTTPS, or FTP URL in the form (http|https|ftp)://[user[:pass]]@host.domain[:port]/path
url_password - |  | The password for use in HTTP basic authentication. If the `url_username` parameter is not specified, the `url_password` parameter will not be used.
url_username - |  | The username for use in HTTP basic authentication. This parameter can be used without `url_password` for sites that allow empty passwords.

use_proxy
boolean

Choices:
- no
- yes ←

If `no`, it will not use a proxy, even if one is defined in an environment variable on the target hosts.

validate_certs
boolean

Choices:
- no
- yes ←

If `no`, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.

variables - |  | List of variables.
zone - |  | The zone from where this host should be polled.

## Examples

    - name: Add host to icinga
      icinga2_host:
        url: "https://icinga2.example.com"
        url_username: "ansible"
        url_password: "a_secret"
        state: present
        name: "{{ ansible_fqdn }}"
        ip: "{{ ansible_default_ipv4.address }}"
      delegate_to: 127.0.0.1

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
data dictionary | always | The data structure used for create, modify or delete of the host
name string | always | The name used to create, modify or delete the host

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Jurgen Brand (@t794104)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.