community.zabbix.zabbix_host module – Create/update/delete Zabbix hosts
Note
This module is part of the community.zabbix collection (version 1.9.0).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.zabbix.
You need further requirements to be able to use this module,
see Requirements for details.
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
Parameters
Parameter |
Comments |
|---|---|
Required certificate issuer. Works only with >= Zabbix 3.0 |
|
Description of the host in Zabbix. |
|
Overwrite the host configuration, even if already present. Choices:
|
|
List of host groups the host is part of. Make sure the Zabbix user used for Ansible can read these groups. |
|
Name of the host in Zabbix. host_name is the unique identifier used and cannot be updated using this module. |
|
List of interfaces to be created for the host (see example below). For more information, review host interface documentation at https://www.zabbix.com/documentation/4.0/manual/api/reference/hostinterface/object Default: |
|
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. Choices:
|
|
Additional details for SNMP host interfaces. Required when type=’snmp’. Works only with Zabbix >= 5.0. Default: |
|
SNMPv3 authentication passphrase. Used when securitylevel=1(authNoPriv) or securitylevel=2(AuthPriv). Default: |
|
SNMPv3 authentication protocol. Used when securitylevel=1(authNoPriv) or securitylevel=2(AuthPriv). 0 (MD5), 1 (SHA) Choices:
|
|
Whether to use bulk SNMP requests. 0 (don’t use bulk requests), 1 (use bulk requests) Choices:
|
|
SNMPv1 and SNMPv2 community string. Required when version=1 or version=2. Default: |
|
SNMPv3 context name. Default: |
|
SNMPv3 privacy passphrase. Used when securitylevel=2(AuthPriv). Default: |
|
SNMPv3 privacy protocol. Used when securitylevel=2(authPriv). 0 (DES), 1 (AES) Choices:
|
|
SNMPv3 security level. 0 (noAuthNoPriv), 1 (authNoPriv), 2 (authPriv). Choices:
|
|
SNMPv3 security name. Default: |
|
SNMP version. 1 (SNMPv1), 2 (SNMPv2c), 3 (SNMPv3) Choices:
|
|
DNS name of the host interface. Required if useip=0. |
|
IP address used by host interface. Required if useip=1. |
|
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) Choices:
|
|
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’ |
|
Interface type to add Numerical values are also accepted for interface type 1 = agent 2 = snmp 3 = ipmi 4 = jmx Choices:
|
|
Connect to host interface with IP address instead of DNS name. 0 (don’t use ip), 1 (use ip) Choices:
|
|
Configure the inventory mode. Choices:
|
|
Add Facts for a zabbix inventory (e.g. Tag) (see example below). Please review the interface documentation for more information on the supported properties https://www.zabbix.com/documentation/3.2/manual/api/reference/host/object#host_inventory |
|
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, 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. also see the last note in the ipmi_authtype documentation |
|
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 also see the last note in the ipmi_authtype documentation |
|
IPMI username. also see the last note in the ipmi_authtype documentation |
|
List of templates linked to the host. |
|
Zabbix user password. If not set the environment variable This option is deprecated with the move to httpapi connection and will be removed in the next release |
|
Zabbix user name. If not set the environment variable This option is deprecated with the move to httpapi connection and will be removed in the next release |
|
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. |
|
Description of the user macro. Works only with >= Zabbix 4.4. Default: |
|
Name of the user macro. Can be in zabbix native format “{$MACRO}” or short format “MACRO”. |
|
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. Choices:
|
|
Value of the user macro. |
|
The name of the Zabbix proxy to be used. |
|
URL of Zabbix server, with protocol (http or https). If not set the environment variable This option is deprecated with the move to httpapi connection and will be removed in the next release |
|
State of the host. On On Choices:
|
|
Monitoring status of the host. Choices:
|
|
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. |
|
Name of the host tag. |
|
Value of the host tag. Default: |
|
The timeout of API request (seconds). This option is deprecated with the move to httpapi connection and will be removed in the next release Default: |
|
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 |
|
Specifies what encryption to use for outgoing connections. Possible values, 1 (no encryption), 2 (PSK), 4 (certificate). Works only with >= Zabbix 3.0 |
|
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 Using this parameter with Zabbix >= 5.4 makes this module non-idempotent. |
|
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 Using this parameter with Zabbix >= 5.4 makes this module non-idempotent. |
|
Required certificate subject. Works only with >= Zabbix 3.0 |
|
If set to False, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates. If not set the environment variable This option is deprecated with the move to httpapi connection and will be removed in the next release Choices:
|
|
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
# Set following variables for Zabbix Server host in play or inventory
- name: Set connection specific variables
set_fact:
ansible_network_os: community.zabbix.zabbix
ansible_connection: httpapi
ansible_httpapi_port: 80
ansible_httpapi_use_ssl: false
ansible_httpapi_validate_certs: false
ansible_zabbix_url_path: 'zabbixeu' # If Zabbix WebUI runs on non-default (zabbix) path ,e.g. http://<FQDN>/zabbixeu
# If you want to use Username and Password to be authenticated by Zabbix Server
- name: Set credentials to access Zabbix Server API
set_fact:
ansible_user: Admin
ansible_httpapi_pass: zabbix
# If you want to use API token to be authenticated by Zabbix Server
# https://www.zabbix.com/documentation/current/en/manual/web_interface/frontend_sections/administration/general#api-tokens
- name: Set API token
set_fact:
ansible_zabbix_auth_key: 8ec0d52432c15c91fcafe9888500cf9a607f44091ab554dbee860f6b44fac895
- name: Create a new host or update an existing host's info
community.zabbix.zabbix_host:
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
community.zabbix.zabbix_host:
host_name: ExampleHost
visible_name: ExampleName
host_groups:
- Example group1
tls_psk_identity: test
tls_connect: 2
tls_psk: 123456789abcdef123456789abcdef12