community.zabbix.zabbix_host – Create/update/delete Zabbix hosts

Note

This plugin is part of the community.zabbix collection (version 1.3.0).

To install it use: ansible-galaxy collection install community.zabbix.

To use it in a playbook, specify: community.zabbix.zabbix_host.

Synopsis

  • This module allows you to create, modify and delete Zabbix host entries and associated group and template data.

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 2.6

  • zabbix-api >= 0.5.4

Parameters

Parameter Choices/Defaults Comments
ca_cert
string
Required certificate issuer.
Works only with >= Zabbix 3.0

aliases: tls_issuer
description
string
Description of the host in Zabbix.
force
boolean
    Choices:
  • no
  • yes ←
Overwrite the host configuration, even if already present.
host_groups
list / elements=string
List of host groups the host is part of.
host_name
string / required
Name of the host in Zabbix.
host_name is the unique identifier used and cannot be updated using this module.
http_login_password
string
Basic Auth password
http_login_user
string
Basic Auth login
interfaces
list / elements=dictionary
Default:
[]
List of interfaces to be created for the host (see example below).
For more information, review host interface documentation at
bulk
integer
    Choices:
  • 0
  • 1
Default:
1
Whether to use bulk SNMP requests.
Only valid when interface type='snmp'.
0 (don't use bulk requests), 1 (use bulk requests)
Works only with Zabbix <= 4.4 and is silently ignored in higher versions.
Use details with Zabbix >= 5.0.
details
dictionary
Default:
{}
Additional details for SNMP host interfaces.
Required when type='snmp'.
Works only with Zabbix >= 5.0.
authpassphrase
string
Default:
""
SNMPv3 authentication passphrase.
Used when securitylevel=1(authNoPriv) or securitylevel=2(AuthPriv).
authprotocol
integer
    Choices:
  • 0
  • 1
Default:
0
SNMPv3 authentication protocol.
Used when securitylevel=1(authNoPriv) or securitylevel=2(AuthPriv).
0 (MD5), 1 (SHA)
bulk
integer
    Choices:
  • 0
  • 1
Default:
1
Whether to use bulk SNMP requests.
0 (don't use bulk requests), 1 (use bulk requests)
community
string
SNMPv1 and SNMPv2 community string.
Required when version=1 or version=2.
contextname
string
Default:
""
SNMPv3 context name.
privpassphrase
string
Default:
""
SNMPv3 privacy passphrase.
Used when securitylevel=2(AuthPriv).
privprotocol
integer
    Choices:
  • 0
  • 1
Default:
0
SNMPv3 privacy protocol.
Used when securitylevel=2(authPriv).
0 (DES), 1 (AES)
securitylevel
integer
    Choices:
  • 0
  • 1
  • 2
Default:
0
SNMPv3 security level.
0 (noAuthNoPriv), 1 (authNoPriv), 2 (authPriv).
securityname
string
Default:
""
SNMPv3 security name.
version
integer
    Choices:
  • 1
  • 2
  • 3
Default:
2
SNMP version.
1 (SNMPv1), 2 (SNMPv2c), 3 (SNMPv3)
dns
string
Default:
""
DNS name of the host interface.
Required if useip=0.
ip
string
Default:
""
IP address used by host interface.
Required if useip=1.
main
integer
    Choices:
  • 0
  • 1
Default:
0
Whether the interface is used as default.
If multiple interfaces with the same type are provided, only one can be default.
0 (not default), 1 (default)
port
string
Port used by host interface.
If not specified, default port for each type of interface is used
10050 if type='agent'
161 if type='snmp'
623 if type='ipmi'
12345 if type='jmx'
type
string / required
    Choices:
  • agent
  • 1
  • snmp
  • 2
  • ipmi
  • 3
  • jmx
  • 4
Interface type to add
Numerical values are also accepted for interface type
1 = agent
2 = snmp
3 = ipmi
4 = jmx
useip
integer
    Choices:
  • 0
  • 1
Default:
0
Connect to host interface with IP address instead of DNS name.
0 (don't use ip), 1 (use ip)
inventory_mode
string
    Choices:
  • automatic
  • manual
  • disabled
Configure the inventory mode.
inventory_zabbix
dictionary
Add Facts for a zabbix inventory (e.g. Tag) (see example below).
Please review the interface documentation for more information on the supported properties
ipmi_authtype
integer
IPMI authentication algorithm.
Please review the Host object documentation for more information on the supported properties
https://www.zabbix.com/documentation/3.4/manual/api/reference/host/object
Possible values are, 0 (none), 1 (MD2), 2 (MD5), 4 (straight), 5 (OEM), 6 (RMCP+), with -1 being the API default.
Please note that the Zabbix API will treat absent settings as default when updating any of the ipmi_-options; this means that if you attempt to set any of the four options individually, the rest will be reset to default values.
ipmi_password
string
IPMI password.
also see the last note in the ipmi_authtype documentation
ipmi_privilege
integer
IPMI privilege level.
Please review the Host object documentation for more information on the supported properties
https://www.zabbix.com/documentation/3.4/manual/api/reference/host/object
Possible values are 1 (callback), 2 (user), 3 (operator), 4 (admin), 5 (OEM), with 2 being the API default.
also see the last note in the ipmi_authtype documentation
ipmi_username
string
IPMI username.
also see the last note in the ipmi_authtype documentation
link_templates
list / elements=string
List of templates linked to the host.
login_password
string / required
Zabbix user password.
login_user
string / required
Zabbix user name.
macros
list / elements=dictionary
List of user macros to assign to the zabbix host.
Providing macros=[] with force=yes will clean all of the existing user macros from the host.

aliases: user_macros
description
string
Default:
""
Description of the user macro.
Works only with >= Zabbix 4.4.
macro
string / required
Name of the user macro.
Can be in zabbix native format "{$MACRO}" or short format "MACRO".
type
string
    Choices:
  • text ←
  • secret
Type of the macro.
Works only with >= Zabbix 5.0.
Since value is not returned by API for secret macros, there is no reliable way to detect changes in the content of secret macro value.
To update secret macro value, please update description alongside it so it passes the check.
value
string / required
Value of the user macro.
proxy
string
The name of the Zabbix proxy to be used.
server_url
string / required
URL of Zabbix server, with protocol (http or https). url is an alias for server_url.

aliases: url
state
string
    Choices:
  • present ←
  • absent
State of the host.
On present, it will create if host does not exist or update the host if the associated data is different.
On absent will remove a host if it exists.
status
string
    Choices:
  • enabled ←
  • disabled
Monitoring status of the host.
tags
list / elements=dictionary
List of host tags to assign to the zabbix host.
Works only with >= Zabbix 4.2.
Providing tags=[] with force=yes will clean all of the tags from the host.

aliases: host_tags
tag
string / required
Name of the host tag.
value
string
Default:
""
Value of the host tag.
timeout
integer
Default:
10
The timeout of API request (seconds).
tls_accept
integer
Default:
1
Specifies what types of connections are allowed for incoming connections.
The tls_accept parameter accepts values of 1 to 7
Possible values, 1 (no encryption), 2 (PSK), 4 (certificate).
Values can be combined.
Works only with >= Zabbix 3.0
tls_connect
integer
Default:
1
Specifies what encryption to use for outgoing connections.
Possible values, 1 (no encryption), 2 (PSK), 4 (certificate).
Works only with >= Zabbix 3.0
tls_psk
string
PSK value is a hard to guess string of hexadecimal digits.
The preshared key, at least 32 hex digits. Required if either tls_connect or tls_accept has PSK enabled.
Works only with >= Zabbix 3.0
tls_psk_identity
string
It is a unique name by which this specific PSK is referred to by Zabbix components
Do not put sensitive information in the PSK identity string, it is transmitted over the network unencrypted.
Works only with >= Zabbix 3.0
tls_subject
string
Required certificate subject.
Works only with >= Zabbix 3.0
validate_certs
boolean
    Choices:
  • no
  • yes ←
If set to False, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.
visible_name
string
Visible name of the host in Zabbix.

Notes

Note

  • If you use login_password=zabbix, the word “zabbix” is replaced by “****” in all module output, because login_password uses no_log. See this FAQ for more information.

Examples

- name: Create a new host or update an existing host's info
  local_action:
    module: community.zabbix.zabbix_host
    server_url: http://monitor.example.com
    login_user: username
    login_password: password
    host_name: ExampleHost
    visible_name: ExampleName
    description: My ExampleHost Description
    host_groups:
      - Example group1
      - Example group2
    link_templates:
      - Example template1
      - Example template2
    status: enabled
    state: present
    inventory_mode: manual
    inventory_zabbix:
      tag: "{{ your_tag }}"
      alias: "{{ your_alias }}"
      notes: "Special Informations: {{ your_informations | default('None') }}"
      location: "{{ your_location }}"
      site_rack: "{{ your_site_rack }}"
      os: "{{ your_os }}"
      hardware: "{{ your_hardware }}"
    ipmi_authtype: 2
    ipmi_privilege: 4
    ipmi_username: username
    ipmi_password: password
    interfaces:
      - type: 1
        main: 1
        useip: 1
        ip: 10.xx.xx.xx
        dns: ""
        port: "10050"
      - type: 4
        main: 1
        useip: 1
        ip: 10.xx.xx.xx
        dns: ""
        port: "12345"
    proxy: a.zabbix.proxy
    macros:
      - macro: '{$EXAMPLEMACRO}'
        value: ExampleMacroValue
      - macro: EXAMPLEMACRO2
        value: ExampleMacroValue2
        description: Example desc that work only with Zabbix 4.4 and higher
    tags:
      - tag: ExampleHostsTag
      - tag: ExampleHostsTag2
        value: ExampleTagValue

- name: Update an existing host's TLS settings
  local_action:
    module: community.zabbix.zabbix_host
    server_url: http://monitor.example.com
    login_user: username
    login_password: password
    host_name: ExampleHost
    visible_name: ExampleName
    host_groups:
      - Example group1
    tls_psk_identity: test
    tls_connect: 2
    tls_psk: 123456789abcdef123456789abcdef12

Authors

  • Cove (@cove)

  • Tony Minfei Ding (!UNKNOWN)

  • Harrison Gu (@harrisongu)

  • Werner Dijkerman (@dj-wasabi)

  • Eike Frost (@eikef)