diff options
Diffstat (limited to 'ansible_collections/community/zabbix/docs')
8 files changed, 2100 insertions, 0 deletions
diff --git a/ansible_collections/community/zabbix/docs/PUBLISHING_TO_GALAXY.md b/ansible_collections/community/zabbix/docs/PUBLISHING_TO_GALAXY.md new file mode 100644 index 000000000..7258bf6c8 --- /dev/null +++ b/ansible_collections/community/zabbix/docs/PUBLISHING_TO_GALAXY.md @@ -0,0 +1,41 @@ +# Publishing New Versions + +## Steps to take on forked repository + +1. Create new branch X.Y.Zprep. +2. Check all merged PRs since last release and verify they had changelog fragments included. If not add them to _changelogs/fragments/missing.yml_ and commit. +3. Generate a changelog entries for new version: + + + ``` + # python3 -m venv antsibull-env && source antsibull-env/bin/activate && pip3 install antsibull-changelog + antsibull-changelog release --version X.Y.Z --date YYYY-MM-DD + ``` + +4. Update `galaxy.yml` file and `requirements.yml` example in `README.md` with the new `version` for the collection and commit. +5. Push new branch for the review `git push origin X.Y.Zprep`. +6. Before merging, ensure that date used for `antsibull-changelog` command is consistent with the day that PR was merged on. + +## Steps to take on ansible-collections/community.zabbix + +1. After merging the branch from previous steps, tag the version via git and push to GitHub: + + + ``` + git tag -a X.Y.Z + git push origin X.Y.Z + ``` + +2. Create new Release pointing to new X.Y.Z tag https://github.com/ansible-collections/community.zabbix/releases + +Additional manual steps are required when automatic publish to Ansible Galaxy is not enabled in the repository. This +requires a user who has access to the `community.zabbix` namespace on Ansible Galaxy to publish the build artifact. + +3. Run the following commands to build and release the new version on Galaxy: + + ``` + ansible-galaxy collection build + ansible-galaxy collection publish ./community-zabbix-$VERSION_HERE.tar.gz + ``` + +After the version is published, verify it exists on the [Zabbix Collection Galaxy page](https://galaxy.ansible.com/community/zabbix). diff --git a/ansible_collections/community/zabbix/docs/RELEASE.md b/ansible_collections/community/zabbix/docs/RELEASE.md new file mode 100644 index 000000000..0c6cc2e81 --- /dev/null +++ b/ansible_collections/community/zabbix/docs/RELEASE.md @@ -0,0 +1,46 @@ +# Release cycle and versioning + +## Versioning +Versioning is using SemVer (X.Y.Z): +- The X is a **major version** and is incremented when: + - Support for older Zabbix versions is removed. + - Support for older Ansible versions is removed. + - Support for older Python versions is removed. + - Modules, roles or plugins are removed. + - Module or role functionality is removed. + - Other breaking changes or backward-incompatible changes are introduced. + +- The Y is a **minor version** and is incremented when: + - Support for new Zabbix versions is added. + - Support for new Ansible versions is added. + - Support for new Python versions is added. + - A new module, role, plugin, etc., is added. + - New features are introduced to modules, roles, plugins. + - A functionality of components is adjusted in a backward-compatible way. + +- The Z is a **patch version** and is incremented when: + - Bugs are fixed in a backward-compatible way. + - Documentation fixes and smaller changes are introduced. +## Releases +Release dates are not fixed. Instead, they will be discussed at the beginning of each month following this guideline: +- The version increment will depend on the content that will be included in the release, as discussed in the *Versioning* section. +- New collection releases may be a result of this discussion if necessary. +- There may be several releases during the month if needed. +## Collection support +The latest release of the community.zabbix is always supported. +Older releases, which are included in the still supported Ansible versions, may obtain occasional backports or bug fixes when necessary. [1] + +[1] [Collection versioning requirements](https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#versioning-and-deprecation) +## Branches +Branch *main* always holds the code for the latest supported release. +New branch *stable-X.Y* is pushed before starting a new *major (X+1)* version development in the main branch. + +The *stable-X.Y* branch provides a way to merge any necessary backports and release bug fixes for older major versions of this collection while they are still included in currently supported ansible releases. +> For example, if the current version of the collection is *1.3.2* and a new version *2.0.0* is being released, the branch *stable-1.Y* should be pushed prior to the release, matching the last commit that was included with the *1.3.2* release. + +## Merging +Merging follows this guideline: +- *Main branch* (previously master branch) is the current branch. +- *stable-X.Y* is a separate branch used to fix issues in older supported collection releases. +- There should be a separate branch for each contribution. +- There should be a separate pull request for each version increment. diff --git a/ansible_collections/community/zabbix/docs/UPGRADE.md b/ansible_collections/community/zabbix/docs/UPGRADE.md new file mode 100644 index 000000000..7784f5842 --- /dev/null +++ b/ansible_collections/community/zabbix/docs/UPGRADE.md @@ -0,0 +1,194 @@ +__Upgrade__ + +Table of content + +- [1.0.0](#100) + * [Roles](#roles) + + [Proxy](#proxy) + + [Java Gateway](#java-gateway) +- [0.2.0](#020) + * [Roles](#roles-1) + + [Agent](#agent) + + [Server](#server) + + [Proxy](#proxy-1) + + [Web](#web) + + [Java Gateway](#java-gateway-1) + +This document provides an overview of all the changes that are needed to be applied to have a correctly working environment per version. If a version is not part of this document, then there are no changes needed to apply. + +## 1.5.0 + +### Roles + +#### Agent + +The following properties are added in the `zabbix_agent` role. + +* `zabbix_api_timeout = 30` +* `zabbix_agent_tls_subject = "{{ zabbix_agent_tlsservercertsubject }}"` +* `zabbix_agent2_server = "{{ zabbix_agent_server }}"` +* `zabbix_agent2_serveractive = "{{ zabbix_agent_serveractive }}"` +* `zabbix_agent2_allow_key = "{{ zabbix_agent_allow_key }}"` +* `zabbix_agent2_deny_key = "{{ zabbix_agent_deny_key }}"` +* `zabbix_agent2_tls_subject = "{{ zabbix_agent2_tlsservercertsubject }}"` + +NOTE: The original properties can still be used but it's suggested to update to +use the new ones. + +The following properties are renamed in the `zabbix_agent` role. + +| From | To | +|-------------------------------|-------------------------------| +| zabbix_url | zabbix_api_server_url | +| zabbix_agent_server_url | zabbix_api_server_url | +| zabbix_http_user | zabbix_api_http_user | +| zabbix_http_password | zabbix_api_http_password | +| zabbix_api_user | zabbix_api_login_user | +| zabbix_api_pass | zabbix_api_login_pass | +| zabbix_validate_certs | zabbix_api_validate_certs | +| zabbix_create_hostgroup | zabbix_agent_hostgroups_state | +| zabbix_macros | zabbix_agent_macros | +| zabbix_inventory_mode | zabbix_agent_inventory_mode | +| zabbix_link_templates | zabbix_agent_link_templates | +| zabbix_proxy | zabbix_agent_proxy | +| zabbix_update_host | zabbix_agent_host_update | +| zabbix_create_host | zabbix_agent_host_state | +| zabbix_visible_hostname | zabbix_agent_visible_hostname | + +NOTE: the old parameters are still valid but it's suggested to update to use the +new ones. + +#### Proxy + +The following properties are added in the `zabbix_proxy` role. + +* `zabbix_api_timeout = 30` +* `zabbix_proxy_tls_subject = "{{ zabbix_proxy_tlsservercertsubject }}"` + +The following properties are renamed in the `zabbix_proxy` role. + +| From | To | +|----------------------------|---------------------------------| +| zabbix_server_host | zabbix_proxy_server | +| zabbix_server_port | zabbix_proxy_serverport | +| zabbix_proxy_localbuffer | zabbix_proxy_proxylocalbuffer | +| zabbix_proxy_offlinebuffer | zabbix_proxy_proxyofflinebuffer | +| zabbix_create_proxy | zabbix_proxy_state | +| zabbix_url | zabbix_api_server_url | +| zabbix_http_user | zabbix_api_http_user | +| zabbix_http_password | zabbix_api_http_password | +| zabbix_api_user | zabbix_api_login_user | +| zabbix_api_pass | zabbix_api_login_pass | +| zabbix_validate_certs | zabbix_api_validate_certs | + +NOTE: the old parameters are still valid but it's suggested to update to use the +new ones. + +## 1.0.0 + +### Roles + +#### Proxy + +The following property is renamed in the `zabbix_proxy` role. + +|From|To| +|----|--| +|`zabbix_version`|`zabbix_proxy_version`| + +NOTE: The `zabbix_version` can still be used, but will be deprecated in later releases. + +#### Java Gateway + +The following properties are renamed in the `zabbix_javagateway` role. + +|From|To| +|----|--| +|`zabbix_version`|`zabbix_javagateway_version`| +|`javagateway_package_state`|`zabbix_javagateway_package_state`| +|`javagateway_pidfile`|`zabbix_javagateway_pidfile`| +|`javagateway_listenip`|`zabbix_javagateway_listenip`| +|`javagateway_listenport`|`zabbix_javagateway_listenport`| +|`javagateway_startpollers`|`zabbix_javagateway_startpollers`| + +NOTE: The `zabbix_version` can still be used, but will be deprecated in later releases. + +## 0.2.0 + +### Roles + +#### Agent + +A 1-on-1 copy of the Ansible role `dj-wasabi.zabbix-agent` to this collection. Due to naming of roles as part of a collection, some characters (Like the `-`) are not allowed anymore. This role is therefore renamed from `zabbix-agent` to `zabbix_agent`. + +Example of using the role in this collection: +```yaml +- hosts: all + roles: + - role: community.zabbix.zabbix_agent + zabbix_agent_server: 192.168.33.30 + zabbix_agent_serveractive: 192.168.33.30 +``` + +#### Server + +A 1-on-1 copy of the Ansible role `dj-wasabi.zabbix-server` to this collection. Due to naming of roles as part of a collection, some characters (Like the `-`) are not allowed anymore. This role is therefore renamed from `zabbix-server` to `zabbix_server`. + +Example of using the role in this collection:: +```yaml +- hosts: zabbix-server + roles: + - role: community.zabbix.zabbix_server + zabbix_server_database: mysql + zabbix_server_database_long: mysql + zabbix_server_dbport: 3306 +``` + +#### Proxy + +A 1-on-1 copy of the Ansible role `dj-wasabi.zabbix-proxy` to this collection. Due to naming of roles as part of a collection, some characters (Like the `-`) are not allowed anymore. This role is therefore renamed from `zabbix-proxy` to `zabbix_proxy`. + +Example of using the role in this collection:: +```yaml +- hosts: zabbix-proxy + roles: + - role: community.zabbix.zabbix_proxy + zabbix_proxy_server: 192.168.1.1 + zabbix_server_database: mysql + zabbix_server_database_long: mysql + zabbix_server_dbport: 3306 +``` + +#### Web + +A 1-on-1 copy of the Ansible role `dj-wasabi.zabbix-web` to this collection. Due to naming of roles as part of a collection, some characters (Like the `-`) are not allowed anymore. This role is therefore renamed from `zabbix-web` to `zabbix_web`. + +Example of using the role in this collection:: +```yaml +- hosts: zabbix-web + become: yes + roles: + - role: geerlingguy.apache + - role: community.zabbix.zabbix_web + zabbix_url: zabbix.mydomain.com + zabbix_server_hostname: zabbix-server + zabbix_server_database: mysql + zabbix_server_database_long: mysql + zabbix_server_dbport: 3306 +``` + +#### Java Gateway + +A 1-on-1 copy of the Ansible role `dj-wasabi.zabbix-javagateway` to this collection. Due to naming of roles as part of a collection, some characters (Like the `-`) are not allowed anymore. This role is therefore renamed from `zabbix-javagateway` to `zabbix_javagateway`. + +Example of using the role in this collection:: +```yaml +- hosts: zabbix-server + roles: + - role: community.zabbix.zabbix_server + zabbix_server_database: mysql + zabbix_server_database_long: mysql + zabbix_server_dbport: 3306 + zabbix_server_javagateway: 192.168.1.1 + - role: community.zabbix.zabbix_javagateway +``` diff --git a/ansible_collections/community/zabbix/docs/ZABBIX_AGENT_ROLE.md b/ansible_collections/community/zabbix/docs/ZABBIX_AGENT_ROLE.md new file mode 100644 index 000000000..f3fe06c9d --- /dev/null +++ b/ansible_collections/community/zabbix/docs/ZABBIX_AGENT_ROLE.md @@ -0,0 +1,556 @@ +# community.zabbix.zabbix_agent role + + + +**Table of Contents** + +- [Requirements](#requirements) + * [Operating systems](#operating-systems) + + [Windows](#windows) + * [Local system access](#local-system-access) + * [Zabbix Versions](#zabbix-versions) +- [Getting started](#getting-started) + * [Minimal Configuration](#minimal-configuration) + * [Issues](#issues) +- [Role Variables](#role-variables) + * [Main variables](#main-variables) + + [Overall Zabbix](#overall-zabbix) + + [SElinux](#selinux) + + [Zabbix Agent](#zabbix-agent) + + [Zabbix Agent vs Zabbix Agent 2 configuration](#zabbix-agent-vs-zabbix-agent-2-configuration) + * [TLS Specific configuration](#tls-specific-configuration) + * [Zabbix API variables](#zabbix-api-variables) + * [Windows Variables](#windows-variables) + * [macOS Variables](#macos-variables) + * [Docker Variables](#docker-variables) + * [FirewallD/Iptables](#firewalld-iptables) + * [IPMI variables](#ipmi-variables) + * [proxy](#proxy) +- [Dependencies](#dependencies) +- [Example Playbook](#example-playbook) + * [zabbix_agent2_plugins](#zabbix-agent2-plugins) + * [agent_interfaces](#agent-interfaces) + * [Other interfaces](#other-interfaces) + * [Vars in role configuration](#vars-in-role-configuration) + * [Combination of group_vars and playbook](#combination-of-group-vars-and-playbook) + * [Example for TLS PSK encrypted agent communication](#example-for-tls-psk-encrypted-agent-communication) +- [Molecule](#molecule) +- [Deploying Userparameters](#deploying-userparameters) +- [License](#license) +- [Author Information](#author-information) + +# Requirements +## Operating systems +This role will work on the following operating systems: + + * Red Hat + * Fedora + * Debian + * Ubuntu + * opensuse + * Windows (Best effort) + * macOS + +So, you'll need one of those operating systems.. :-) +Please send Pull Requests or suggestions when you want to use this role for other Operating systems. + +## Ansible 2.10 and higher + +With the release of Ansible 2.10, modules have been moved into collections. With the exception of ansible.builtin modules, this means additonal collections must be installed in order to use modules such as seboolean (now ansible.posix.seboolean). The following collections are now required: `ansible.posix`and `community.general`. Installing the collections: + +```sh +ansible-galaxy collection install ansible.posix +ansible-galaxy collection install community.general +``` +If you are willing to create host_groups and hosts in Zabbix via API as a part of this role execution then you need to install `ansible.netcommon` collection too: + +``` +ansible-galaxy collection install ansible.netcommon +``` + +### Docker + +When you are a Docker user and using Ansible 2.10 or newer, then there is a dependency on the collection named `community.docker`. This collection is needed as the `docker_` modules are now part of collections and not standard in Ansible anymmore. Installing the collection: + +```sh +ansible-galaxy collection install community.docker +``` + +### Windows + +When you are a Windows user and using Ansible 2.10 or newer, then there are dependencies on collections named `ansible.windows` and `community.windows`. These collections are needed as the `win_` modules are now part of collections and not standard in Ansible anymmore. Installing the collections: + +```sh +ansible-galaxy collection install ansible.windows +ansible-galaxy collection install community.windows +``` + +For more information, see: https://github.com/ansible-collections/community.zabbix/issues/236 + +## Local system access + +To successfully complete the install the role requires `python-netaddr` on the controller to be able to manage IP addresses. This requires that the library is available on your local machine (or that `pip` is installed to be able to run). This will likely mean that running the role will require `sudo` access to your local machine and therefore you may need the `-K` flag to be able to enter your local machine password if you are not running under root. + +## Zabbix Versions + +See the following list of supported Operating systems with the Zabbix releases: + +| Zabbix | 6.4 | 6.2 | 6.0 | 5.4 | 5.2 | 5.0 (LTS)| 4.4 | 4.0 (LTS) | 3.0 (LTS) | +|---------------------|-----|-----|-----|-----|-----|----------|-----|-----------|-----------| +| Red Hat Fam 9 | V | V | V | | | | | | | +| Red Hat Fam 8 | V | V | V | V | V | V | V | | | +| Red Hat Fam 7 | V | V | V | V | V | V | V | V | V | +| Red Hat Fam 6 | V | V | V | V | V | V | | | V | +| Red Hat Fam 5 | | | V | V | V | V | | | V | +| Fedora | | | | | | | V | V | | +| Ubuntu 20.04 focal | V | V | V | V | V | V | | V | | +| Ubuntu 18.04 bionic | V | V | V | V | V | V | V | V | | +| Ubuntu 16.04 xenial | V | V | V | V | V | V | V | V | | +| Ubuntu 14.04 trusty | V | V | V | V | V | V | V | V | V | +| Debian 10 buster | V | V | V | V | V | V | V | | | +| Debian 9 stretch | V | V | | V | V | V | V | V | | +| Debian 8 jessie | | | | | V | V | V | V | V | +| Debian 7 wheezy | | | | | | | | V | V | +| macOS 10.15 | | | | | | | V | V | | +| macOS 10.14 | | | | | | | V | V | | + +# Getting started + +## Minimal Configuration + +In order to get the Zabbix Agent running, you'll have to define the following properties before executing the role: + +* `zabbix_agent_version` +* `zabbix_agent(2)_server` +* `zabbix_agent(2)_serveractive` (When using active checks) + +The `zabbix_agent_version` is optional. The latest available major.minor version of Zabbix will be installed on the host(s). If you want to use an older version, please specify this in the major.minor format. Example: `zabbix_agent_version: 4.0`, `zabbix_agent_version: 3.4` or `zabbix_agent_version: 2.2`. + +The `zabbix_agent(2)_server` (and `zabbix_agent(2)_serveractive`) should contain the ip or fqdn of the host running the Zabbix Server. + +## Issues + +Due to issue discussed on [#291](https://github.com/dj-wasabi/ansible-zabbix-agent/issues/291), the Ansible Version 2.9.{0,1,2} isn't working correctly on Windows related targets. + +# Role Variables + +## Main variables + +The following is an overview of all available configuration default for this role. + +### Overall Zabbix + +* `zabbix_agent_version`: This is the version of zabbix. Default: The highest supported version for the operating system. Can be overridden to 6.2, 6.0, 5.4, 5.2 5.0, 4.4, 4.0, 3.4, 3.2, 3.0, 2.4, or 2.2. Previously the variable `zabbix_version` was used directly but it could cause [some inconvenience](https://github.com/dj-wasabi/ansible-zabbix-agent/pull/303). That variable is maintained by retrocompativility. +* `zabbix_agent_version_minor`: When you want to specify a minor version to be installed. Is also used for `zabbix_sender` and `zabbix_get`. RedHat only. Default set to: `*` (latest available) +* `zabbix_repo`: Default: `zabbix` + * `epel`: install agent from EPEL repo + * `zabbix`: (default) install agent from Zabbix repo + * `other`: install agent from pre-existing or other repo +* `zabbix_repo_yum`: A list with Yum repository configuration. +* `zabbix_repo_yum_schema`: Default: `https`. Option to change the web schema for the yum repository(http/https) +* `zabbix_repo_yum_disabled`: A string with repository names that should be disabled when installing Zabbix component specific packages. Is only used when `zabbix_repo_yum_enabled` contains 1 or more repositories. Default `*`. +* `zabbix_repo_yum_enabled`: A list with repository names that should be enabled when installing Zabbix component specific packages. + +### SElinux + +* `zabbix_selinux`: Default: `False`. Enables an SELinux policy so that the server will run. + +### Zabbix Agent + +* `zabbix_agent_ip`: The IP address of the host. When not provided, it will be determined via the `ansible_default_ipv4` fact. +* `zabbix_agent2`: Default: `False`. When you want to install the `Zabbix Agent2` instead of the "old" `Zabbix Agent`. +* `zabbix_agent_listeninterface`: Interface zabbix-agent listens on. Leave blank for all. +* `zabbix_agent_package_remove`: If `zabbix_agent2: True` and you want to remove the old installation. Default: `False`. +* `zabbix_agent_package`: The name of the zabbix-agent package. Default: `zabbix-agent`. In case for EPEL, it is automatically renamed. +* `zabbix_sender_package`: The name of the zabbix-sender package. Default: `zabbix-sender`. In case for EPEL, it is automatically renamed. +* `zabbix_get_package`: The name of the zabbix-get package. Default: `zabbix-get`. In case for EPEL, it is automatically renamed. +* `zabbix_agent_package_state`: If Zabbix-agent needs to be `present` or `latest`. +* `zabbix_agent_interfaces`: A list that configured the interfaces you can use when configuring via API. +* `zabbix_agent_install_agent_only`: Only install the Zabbix Agent and not the `zabbix-sender` and `zabbix-get` packages. Default: `False` +* `zabbix_agent_userparameters`: Default: `[]]`. List of userparameter names and scripts (if any). Detailed description is given in the [Deploying Userparameters](#deploying-userparameters) section. + * `name`: Userparameter name (should be the same with userparameter template file name) + * `scripts_dir`: Directory name of the custom scripts needed for userparameters +* `zabbix_agent_userparameters_templates_src`: indicates the relative path (from `templates/`) where userparameter templates are searched +* `zabbix_agent_userparameters_scripts_src`: indicates the relative path (from `files/`) where userparameter scripts are searched +* `zabbix_agent_runas_user`: Drop privileges to a specific, existing user on the system. Only has effect if run as 'root' and AllowRoot is disabled. +* `zabbix_agent_become_on_localhost`: Default: `True`. Set to `False` if you don't need to elevate privileges on localhost to install packages locally with pip. +* `zabbix_install_pip_packages`: Default: `True`. Set to `False` if you don't want to install the required pip packages. Useful when you control your environment completely. +* `zabbix_agent_apt_priority`: Add a weight (`Pin-Priority`) for the APT repository. +* `zabbix_agent_conf_mode`: Default: `0644`. The "mode" for the Zabbix configuration file. +* `zabbix_agent_dont_detect_ip`: Default `false`. When set to `true`, it won't detect available ip addresses on the host and no need for the Python module `netaddr` to be installed. +* `zabbix_agent_chassis`: Default: `false`. When set to `true`, it will give Zabbix Agent access to the Linux DMI table allowing system.hw.chassis info to populate. + +### Zabbix Agent vs Zabbix Agent 2 configuration + +The following provides an overview of all the properties that can be set in the Zabbix Agent configuration file. When `(2)` is used in the name of the property, like `zabbix_agent(2)_pidfile`, it will show that you can configure `zabbix_agent_pidfile` for the Zabbix Agent configuration file and `zabbix_agent2_pidfile` for the Zabbix Agent 2 configuration file. + +Otherwise it just for the Zabbix Agent or for the Zabbix Agent 2. + +* `zabbix_agent(2)_server`: The ip address for the zabbix-server or zabbix-proxy. +* `zabbix_agent(2)_serveractive`: The ip address for the zabbix-server or zabbix-proxy for active checks. +* `zabbix_agent(2)_allow_key`: list of AllowKey configurations. +* `zabbix_agent(2)_deny_key`: list of DenyKey configurations. +* `zabbix_agent(2)_pidfile`: name of pid file. +* `zabbix_agent(2)_logfile`: name of log file. +* `zabbix_agent(2)_logfilesize`: maximum size of log file in mb. +* `zabbix_agent(2)_logtype`: Specifies where log messages are written to +* `zabbix_agent(2)_debuglevel`: specifies debug level +* `zabbix_agent(2)_sourceip`: source ip address for outgoing connections. +* `zabbix_agent_enableremotecommands`: whether remote commands from zabbix server are allowed. +* `zabbix_agent_logremotecommands`: enable logging of executed shell commands as warnings. +* `zabbix_agent(2)_listenport`: agent will listen on this port for connections from the server. +* `zabbix_agent2_statusport`: Agent will listen on this port for HTTP status requests. +* `zabbix_agent(2)_listenip`: list of comma delimited ip addresses that the agent should listen on. +* `zabbix_agent_startagents`: number of pre-forked instances of zabbix_agentd that process passive checks. +* `zabbix_agent(2)_hostname`: unique, case sensitive hostname. +* `zabbix_agent(2)_hostnameitem`: item used for generating hostname if it is undefined. +* `zabbix_agent(2)_hostmetadata`: optional parameter that defines host metadata. +* `zabbix_agent(2)_hostmetadataitem`: optional parameter that defines an item used for getting the metadata. +* `zabbix_agent(2)_refreshactivechecks`: how often list of active checks is refreshed, in seconds. +* `zabbix_agent(2)_buffersend`: do not keep data longer than n seconds in buffer. +* `zabbix_agent(2)_buffersize`: maximum number of values in a memory buffer. the agent will send all collected data to zabbix server or proxy if the buffer is full. +* `zabbix_agent2_enablepersistentbuffer`: 0 - disabled, in-memory buffer is used (default); 1 - use persistent buffer +* `zabbix_agent2_persistentbufferperiod`: Zabbix Agent2 will keep data for this time period in case of no connectivity with Zabbix server or proxy. Older data will be lost. Log data will be preserved. +* `zabbix_agent2_persistentbufferfile`: Zabbix Agent2 will keep SQLite database in this file * n is valid if `EnablePersistentBuffer=1` +* `zabbix_agent_maxlinespersecond`: maximum number of new lines the agent will send per second to zabbix server or proxy processing 'log' and 'logrt' active checks. +* `zabbix_agent_allowroot`: allow the agent to run as 'root'. if disabled and the agent is started by 'root', the agent will try to switch to user 'zabbix' instead. has no effect if started under a regular user. +* `zabbix_agent(2)_zabbix_alias`: sets an alias for parameter. it can be useful to substitute long and complex parameter name with a smaller and simpler one. Can be both a string as an list. +* `zabbix_agent(2)_timeout`: spend no more than timeout seconds on processing +* `zabbix_agent(2)_include`: you may include individual files or all files in a directory in the configuration file. +* `zabbix_agent(2)_include_pattern`: Optional file pattern used for included files. +* `zabbix_agent(2)_include_mode`: The mode for the directory mentioned above. +* `zabbix_agent(2)_unsafeuserparameters`: allow all characters to be passed in arguments to user-defined parameters. +* `zabbix_agent_loadmodulepath`: Full path to location of agent modules. +* `zabbix_agent_loadmodule`: Module to load at agent startup. Modules are used to extend functionality of the agent. +* `zabbix_agent2_controlsocket`: The control socket, used to send runtime commands with '-R' option. +* `zabbix_agent_allowroot`: Allow the agent to run as 'root'. 0 - do not allow, 1 - allow +* `zabbix_agent2_plugins`: A list containing plugin configuration. +* `zabbix_agent(2)_listenbacklog`: The maximum number of pending connections in the queue. + +## TLS Specific configuration + +These variables are specific for Zabbix 3.0 and higher. When `(2)` is used in the name of the property, like `zabbix_agent(2)_tlsconnect`, it will show that you can configure `zabbix_agent_tlsconnect` for the Zabbix Agent configuration file and `zabbix_agent2_tlsconnect` for the Zabbix Agent 2 configuration file. + +* `zabbix_agent(2)_tlsconnect`: How the agent should connect to server or proxy. Used for active checks. + Possible values: + * unencrypted + * psk + * cert +* `zabbix_agent(2)_tlsaccept`: What incoming connections to accept. + Possible values: + * unencrypted + * psk + * cert +* `zabbix_agent(2)_tlscafile`: Full pathname of a file containing the top-level CA(s) certificates for peer certificate verification. +* `zabbix_agent(2)_tlscrlfile`: Full pathname of a file containing revoked certificates. +* `zabbix_agent(2)_tlsservercertissuer`: Allowed server certificate issuer. +* `zabbix_agent(2)_tlsservercertsubject`: Allowed server certificate subject. +* `zabbix_agent(2)_tlscertfile`: Full pathname of a file containing the agent certificate or certificate chain. +* `zabbix_agent(2)_tlskeyfile`: Full pathname of a file containing the agent private key. +* `zabbix_agent(2)_tlspskidentity`: Unique, case sensitive string used to identify the pre-shared key. +* `zabbix_agent(2)_tlspskidentity_file`: Full pathname of a file containing the pre-shared key identity. +* `zabbix_agent(2)_tlspskfile`: Full pathname of a file containing the pre-shared key. +* `zabbix_agent(2)_tlspsk_secret`: The pre-shared secret key that should be placed in the file configured with `agent_tlspskfile`. +* `zabbix_agent(2)_tlspsk_auto`: Enables auto generation and storing of individual pre-shared keys and identities on clients. Is false by default. If set to true and if `zabbix_agent_tlspskfile` and `zabbix_agent_tlspsk_secret` are undefined, it generates the files `/etc/zabbix/tls_psk_auto.identity` and `/etc/zabbix/tls_psk_auto.secret`, which are populated by values automatically (identity is set to hostname, underscore and 4 random alphanumeric digits; secret is 64 random alphanumeric digits) in such a way that the values are generated once and are never overwritten. + +The results are stored in the Ansible variables `zabbix_agent_tlspskidentity` and `zabbix_agent_tlspsk_secret`, so that they may be used later in the code, for example with [zabbix_host](https://docs.ansible.com/ansible/latest/collections/community/zabbix/zabbix_host_module.html) to configure the Zabbix server or with `debug: msg:` to display them to the user. + +## Zabbix API variables + +These variables need to be overridden when you want to make use of the Zabbix API for automatically creating and or updating hosts. + +Host encryption configuration will be set to match agent configuration. + +* `zabbix_api_http_user`: The http user to access zabbix url with Basic Auth. +* `zabbix_api_http_password`: The http password to access zabbix url with Basic Auth. +* `zabbix_api_create_hosts`: Default: `False`. When you want to enable the Zabbix API to create/delete the host. This has to be set to `True` if you want to make use of `zabbix_agent_host_state`. +* `zabbix_api_create_hostgroup`: When you want to enable the Zabbix API to create/delete the hostgroups. This has to be set to `True` if you want to make use of `zabbix_agent_hostgroups_state`.Default: `False` +* `zabbix_api_server_host`: The IP or hostname/FQDN of Zabbix server. Example: zabbix.example.com +* `zabbix_api_server_port`: TCP port to use to connect to Zabbix server. Example: 8080 +* `zabbix_api_use_ssl`: yes (Default) if we need to connect to Zabbix server over HTTPS +* `zabbix_api_validate_certs` : yes (Default) if we need to validate tls certificates of the API. Use `no` in case self-signed certificates are used +* `zabbix_api_login_user`: Username of user which has API access. +* `zabbix_api_login_pass`: Password for the user which has API access. +* `ansible_zabbix_url_path`: URL path if Zabbix WebUI running on non-default (zabbix) path, e.g. if http://<FQDN>/zabbixeu then set to `zabbixeu` +* `zabbix_agent_hostgroups_state`: present (Default) if the hostgroup needs to be created or absent if you want to delete it. This only works when `zabbix_api_create_hostgroup` is set to `True`. +* `zabbix_host_status`: enabled (Default) when host in monitored, disabled when host is disabled for monitoring. +* `zabbix_agent_host_state`: present (Default) if the host needs to be created or absent is you want to delete it. This only works when `zabbix_api_create_hosts` is set to `True`. +* `zabbix_agent_host_update`: yes (Default) if the host should be updated if already present. This only works when `zabbix_api_create_hosts` is set to `True`. +* `zabbix_useuip`: 1 if connection to zabbix-agent is made via ip, 0 for fqdn. +* `zabbix_host_groups`: A list of hostgroups which this host belongs to. +* `zabbix_agent_link_templates`: A list of templates which needs to be link to this host. The templates should exist. +* `zabbix_agent_macros`: A list with macro_key and macro_value for creating hostmacro's. +* `zabbix_agent_tags`: A list with tag and (optionally) value for creating host tags. +* `zabbix_agent_inventory_mode`: Configure Zabbix inventory mode. Needed for building inventory data, manually when configuring a host or automatically by using some automatic population options. This has to be set to `automatic` if you want to make automatically building inventory data. +* `zabbix_agent_visible_hostname` : Configure Zabbix visible name inside Zabbix web UI for the node. +* `zabbix_agent_description`: Description of the host in Zabbix. +* `zabbix_agent_inventory_zabbix`: Adds Facts for a zabbix inventory + +## Windows Variables + +**NOTE** + +_Supporting Windows is a best effort (I don't have the possibility to either test/verify changes on the various amount of available Windows instances). PRs specific to Windows will almost immediately be merged, unless someone is able to provide a Windows test mechanism via Travis for Pull Requests._ +When `(2)` is used in the name of the property, like `zabbix_agent(2)_win_logfile`, it will show that you can configure `zabbix_agent_win_logfile` for the Zabbix Agent configuration file and `zabbix_agent2_win_logfile` for the Zabbix Agent 2 configuration file. + +Otherwise it just for the Zabbix Agent or for the Zabbix Agent 2. + +* `zabbix(2)_win_package`: file name pattern (zip only). This will be used to generate the `zabbix(2)_win_download_link` variable. +* `zabbix_version_long`: The long (major.minor.patch) version of the Zabbix Agent. This will be used to generate the `zabbix(2)_win_package` and `zabbix(2)_win_download_link` variables. This takes precedence over `zabbix_agent_version`. +* `zabbix(2)_win_download_link`: The download url to the `win.zip` file. +* `zabbix_win_install_dir`: The directory where Zabbix needs to be installed. +* `zabbix_win_install_dir_conf`: The directory where Zabbix configuration file needs to be installed. +* `zabbix_win_install_dir_bin`: The directory where Zabbix binary file needs to be installed. +* `zabbix_agent(2)_win_logfile`: The full path to the logfile for the Zabbix Agent. +* `zabbix_agent_win_include`: The directory in which the Zabbix Agent specific configuration files are stored. +* `zabbix_agent_win_svc_recovery`: Enable Zabbix Agent service auto-recovery settings. +* `zabbix_win_firewall_management`: Enable Windows firewall management (add service and port to allow rules). Default: `True` + +## macOS Variables + +* `zabbix_version_long`: The long (major.minor.patch) version of the Zabbix Agent. This will be used to generate the `zabbix_mac_download_link` link. +* `zabbix_mac_download_link`: The download url to the `pkg` file. + +## Docker Variables + +When you don't want to install the Zabbix Agent on the host, but would like to run it in a container then these properties are useful. When `zabbix_agent_docker` is set to `True`, then a +Docker image will be downloaded and a Container will be started. No other installations will be done on the host, with the exception of the PSK file and the "Zabbix Include Directory". + +The following directories are mounted in the Container: + +``` + - /etc/zabbix/zabbix_agentd.d:/etc/zabbix/zabbix_agentd.d + - /:/hostfs:ro + - /etc:/hostfs/etc:ro + - /proc:/hostfs/proc:ro + - /sys:/hostfs/sys:ro + - /var/run:/var/run +``` + +Keep in mind that using the Zabbix Agent in a Container requires changes to the Zabbix Template for Linux as `/proc`, `/sys` and `/etc` are mounted in a directory `/hostfs`. + +* `zabbix_agent_docker`: Default: `False`. When set to `True`, it will install a Docker container on the target host instead of installation on the target. +* `zabbix_agent_docker_state`: Default: `started` +* `zabbix_agent_docker_name`: The name of the Container. Default: `zabbix-agent` +* `zabbix_agent_docker_image`: The name of the Docker image. Default: `zabbix/zabbix-agent` +* `zabbix_agent_docker_image_tag`: The tag of the Docker image. +* `zabbix_agent_docker_user_gid`: The group id of the zabbix user in the Container. +* `zabbix_agent_docker_user_uid`: The user id of the zabbix user in the Container. +* `zabbix_agent_docker_network_mode`: The name of the (Docker) network that should be used for the Container. Default `host`. +* `zabbix_agent_docker_restart_policy`: Default: `unless-stopped`. The restart policy of the Container. +* `zabbix_agent_docker_privileged`: When set to `True`, the container is running in privileged mode. +* `zabbix_agent_docker_ports`: A list with `<PORT>:<PORT>` values to open ports to the container. +* `zabbix_agent_docker_security_opts`: A list with available security options. +* `zabbix_agent_docker_volumes`: A list with all directories that needs to be available in the Container. +* `zabbix_agent_docker_env`: A dict with all environment variables that needs to be set for the Container. + +## FirewallD/Iptables + +* `zabbix_agent_firewall_enable`: If IPtables needs to be updated by opening an TCP port for port configured in `zabbix_agent_listenport`. +* `zabbix_agent_firewall_source`: When provided, IPtables will be configuring to only allow traffic from this IP address/range. +* `zabbix_agent_firewalld_enable`: If firewalld needs to be updated by opening an TCP port for port configured in `zabbix_agent_listenport` and `zabbix_agent_jmx_listenport` if defined. +* `zabbix_agent_firewalld_source`: When provided, firewalld will be configuring to only allow traffic for IP configured in `zabbix_agent_server`. +* `zabbix_agent_firewalld_zone`: When provided, the firewalld rule will be attached to this zone (only if zabbix_agent_firewalld_enable is set to true). The default behavior is to use the default zone define by the remote host firewalld configuration. +* `zabbix_agent_firewall_action`: Default: `insert`. When to `insert` the rule or to `append` to IPTables. +* `zabbix_agent_firewall_chain`: Default `INPUT`. Which `chain` to add the rule to IPTables. + + +## IPMI variables + +* `zabbix_agent_ipmi_authtype`: IPMI authentication algorithm. Possible values are 1 (callback), 2 (user), 3 (operator), 4 (admin), 5 (OEM), with 2 being the API default. +* `zabbix_agent_ipmi_password`: IPMI password. +* `zabbix_agent_ipmi_privilege`: IPMI privilege level. Possible values are 1 (callback), 2 (user), 3 (operator), 4 (admin), 5 (OEM), with 2 being the API default. +* `zabbix_agent_ipmi_username`: IPMI username. + +## proxy + +When the target host does not have access to the internet, but you do have a proxy available then the following properties needs to be set to download the packages via the proxy: + +* `zabbix_http_proxy` +* `zabbix_https_proxy` + +# Dependencies + +There are no dependencies on other roles. + +# Example Playbook + +## zabbix_agent2_plugins + +Specifically for the Zabbix Agent 2, a list of extra plugins can be configured. The following provides an overview of configuring the `SystemRun` plugin by setting the `LogRemoteCommands` to `0`: + +```yaml +zabbix_agent2_plugins: + - name: SystemRun + options: + - parameter: LogRemoteCommands + value: 0 +``` + +In the `zabbix_agent2.conf` an entry will be created with the following content: + +``` +Plugins.SystemRun.LogRemoteCommands=0 +``` + +## agent_interfaces + +This will configure the Zabbix Agent interface on the host. +```yaml +zabbix_agent_interfaces: + - type: 1 + main: 1 + useip: "{{ zabbix_useuip }}" + ip: "{{ zabbix_agent_ip }}" + dns: "{{ ansible_fqdn }}" + port: "{{ zabbix_agent_listenport }}" +``` + +## Other interfaces + +You can also configure the `zabbix_agent_interfaces` to add/configure snmp, jmx and ipmi interfaces. + +You'll have to use one of the following type numbers when configuring it: + +| Type Interface | Nr | +|-----------------|-------| +| Zabbix Agent | 1 | +| snmp | 2 | +| ipmi | 3 | +| jmx | 4 | + +Configuring a snmp interface will look like this: + +``` +zabbix_agent_interfaces: + - type: 2 + main: 1 + useip: "{{ zabbix_useuip }}" + ip: "{{ agent_ip }}" + dns: "{{ ansible_fqdn }}" + port: "{{ agent_listenport }}" +``` + +## Vars in role configuration +Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too: + +```yaml + - hosts: all + roles: + - role: community.zabbix.zabbix_agent + zabbix_agent_server: 192.168.33.30 + zabbix_agent_serveractive: 192.168.33.30 + zabbix_api_server_url: http://zabbix.example.com + zabbix_api_use: true # use zabbix_api_create_hosts and/or zabbix_api_create_hostgroup from 0.8.0 + zabbix_api_login_user: Admin + zabbix_api_login_pass: zabbix + zabbix_agent_host_state: present + zabbix_host_groups: + - Linux Servers + zabbix_agent_link_templates: + - Template OS Linux + - Apache APP Template + zabbix_agent_macros: + - macro_key: apache_type + macro_value: reverse_proxy + macro_type: text + zabbix_agent_tags: + - tag: environment + value: production +``` + +## Combination of group_vars and playbook +You can also use the group_vars or the host_vars files for setting the variables needed for this role. File you should change: `group_vars/all` or `host_vars/<zabbix_server>` (Where <zabbix_server> is the hostname of the machine running Zabbix Server) + +```yaml + zabbix_agent_server: 192.168.33.30 + zabbix_agent_serveractive: 192.168.33.30 + zabbix_api_server_url: http://zabbix.example.com + zabbix_api_use: true # use zabbix_api_create_hosts and/or zabbix_api_create_hostgroup from 0.8.0 + zabbix_api_login_user: Admin + zabbix_api_login_pass: zabbix + zabbix_agent_host_state: present + zabbix_host_groups: + - Linux Servers + zabbix_agent_link_templates: + - Template OS Linux + - Apache APP Template + zabbix_agent_macros: + - macro_key: apache_type + macro_value: reverse_proxy + zabbix_agent_tags: + - tag: environment + value: production +``` + +and in the playbook only specifying: + +```yaml + - hosts: all + roles: + - role: community.zabbix.zabbix_agent +``` + +## Example for TLS PSK encrypted agent communication + +Variables e.g. in the playbook or in `host_vars/myhost`: + +```yaml + zabbix_agent_tlsaccept: psk + zabbix_agent_tlsconnect: psk + zabbix_agent_tlspskidentity: "myhost PSK" + zabbix_agent_tlspsk_secret: b7e3d380b9d400676d47198ecf3592ccd4795a59668aa2ade29f0003abbbd40d + zabbix_agent_tlspskfile: /etc/zabbix/zabbix_agent_pskfile.psk +``` + +# Molecule + +This role is configured to be tested with Molecule. You can find on this page some more information regarding Molecule: + +* http://werner-dijkerman.nl/2016/07/10/testing-ansible-roles-with-molecule-testinfra-and-docker/ +* http://werner-dijkerman.nl/2016/07/27/extending-ansible-role-testing-with-molecule-by-adding-group_vars-dependencies-and-using-travis-ci/ +* http://werner-dijkerman.nl/2016/07/31/testing-ansible-roles-in-a-cluster-setup-with-docker-and-molecule/ + +With each Pull Request, Molecule will be executed via travis.ci. Pull Requests will only be merged once these tests run successfully. + +# Deploying Userparameters + +The following steps are required to install custom userparameters and/or scripts: + +* Put the desired userparameter file in the `templates/userparameters` directory and name it as `<userparameter_name>.j2`. For example: `templates/userparameters/mysql.j2`. You can change the default directory to a custom one modifying `zabbix_agent_userparameters_templates_src` variable. +* Put the scripts directory (if any) in the `files/scripts` directory. For example: `files/scripts/mysql`. You can change the default directory to a custom one modifying `zabbix_agent_userparameters_scripts_src` variable. +* Add `zabbix_agent_userparameters` variable to the playbook as a list of dictionaries and define userparameter name and scripts directory name (if there are no scripts just no not specify the `scripts_dir` variable). + +Example: + +```yaml +- hosts: mysql_servers + tasks: + - include_role: + name: community.zabbix.zabbix_agent + vars: + zabbix_agent_server: zabbix.mydomain.com + zabbix_agent_userparameters: + - name: mysql + scripts_dir: mysql + - name: galera + +``` + +Example of the "templates/userparameters/mysql.j2" file: + +``` +UserParameter=mysql.ping_to,mysqladmin -uroot ping | grep -c alive +``` + +# License + +GNU General Public License v3.0 or later + +See LICENCE to see the full text. + +# Author Information + +Please send suggestion or pull requests to make this role better. Also let us know if you encounter any issues installing or using this role. + +Github: https://github.com/ansible-collections/community.zabbix diff --git a/ansible_collections/community/zabbix/docs/ZABBIX_JAVAGATEWAY_ROLE.md b/ansible_collections/community/zabbix/docs/ZABBIX_JAVAGATEWAY_ROLE.md new file mode 100644 index 000000000..70427d97c --- /dev/null +++ b/ansible_collections/community/zabbix/docs/ZABBIX_JAVAGATEWAY_ROLE.md @@ -0,0 +1,142 @@ +# community.zabbix.zabbix_javagateway role + + + +**Table of Contents** + +- [Overview](#overview) + * [Operating systems](#operating-systems) + * [Zabbix Versions](#zabbix-versions) +- [Role Variables](#role-variables) + * [Main variables](#main-variables) + + [Overall Zabbix](#overall-zabbix) + + [Java Gatewaty](#java-gatewaty) + + [proxy](#proxy) +- [Dependencies](#dependencies) +- [Example Playbook](#example-playbook) +- [Molecule](#molecule) +- [License](#license) +- [Author Information](#author-information) + +# Overview + +## Operating systems + +This role will work on the following operating systems: + + * Red Hat + * Debian + * Ubuntu + +So, you'll need one of those operating systems.. :-) +Please send Pull Requests or suggestions when you want to use this role for other Operating systems. + +## Zabbix Versions + +See the following list of supported Operating systems with the Zabbix releases. + +| Zabbix | 6.4 | 6.2 | 6.0 (LTS) | 5.2 | 5.0 | 4.4 | 4.0 (LTS) | 3.0 (LTS) | +|---------------------|-----|-----|-----------|-----|-----|-----|-----------|-----------| +| Red Hat Fam 8 | V | V | V | V | V | V | | | +| Red Hat Fam 7 | | | | V | V | V | V | V | +| Red Hat Fam 6 | | | | V | V | | | V | +| Red Hat Fam 5 | | | | V | V | | | V | +| Fedora | | | | | | V | V | | +| Ubuntu 20.04 focal | V | V | V | V | V | | V | | +| Ubuntu 18.04 bionic | | | | V | V | V | V | | +| Ubuntu 16.04 xenial | | | | V | V | V | V | | +| Ubuntu 14.04 trusty | | | | V | V | V | V | V | +| Debian 10 buster | V | V | V | V | V | V | | | +| Debian 9 stretch | | | | V | V | V | V | | +| Debian 8 jessie | | | | V | V | V | V | V | +| Debian 7 wheezy | | | | | | | V | V | +| macOS 10.15 | | | | | | V | V | | +| macOS 10.14 | | | | | | V | V | | + +# Role Variables + +## Main variables + +The following is an overview of all available configuration default for this role. + +### Overall Zabbix + +* `zabbix_javagateway_version`: This is the version of zabbix. Default: 5.2. Can be overridden to 5.0, 4.4, 4.0, 3.4, 3.2, 3.0, 2.4, or 2.2. Previously the variable `zabbix_version` was used directly but it could cause [some inconvenience](https://github.com/dj-wasabi/ansible-zabbix-agent/pull/303). That variable is maintained by retrocompativility. +* `zabbix_repo`: Default: `zabbix` + * `epel`: install agent from EPEL repo + * `zabbix`: (default) install agent from Zabbix repo + * `other`: install agent from pre-existing or other repo +* `zabbix_repo_yum`: A list with Yum repository configuration. +* `zabbix_repo_yum_schema`: Default: `https`. Option to change the web schema for the yum repository(http/https) +* `zabbix_repo_yum_disabled`: A string with repository names that should be disabled when installing Zabbix component specific packages. Is only used when `zabbix_repo_yum_enabled` contains 1 or more repositories. Default `*`. +* `zabbix_repo_yum_enabled`: A list with repository names that should be enabled when installing Zabbix component specific packages. +* `zabbix_javagateway_package_state`: Default: `present`. Can be overridden to `latest` to update packages when needed. +* `zabbix_javagateway_conf_mode`: Default: `0644`. The "mode" for the Zabbix configuration file. + +### Java Gatewaty + +* `zabbix_javagateway_pidfile`: Default: `/run/zabbix/zabbix_java_gateway.pid`. The location for the pid file. +* `zabbix_javagateway_listenip`: Default: `0.0.0.0`. The IP address to listen on. +* `zabbix_javagateway_listenport`: Default: `10052`. The port on which Java Gateway is listening on. +* `zabbix_javagateway_startpollers`: Default: `5`. The amount of pollers to start. + +### proxy + +When the target host does not have access to the internet, but you do have a proxy available then the following properties needs to be set to download the packages via the proxy: + +* `zabbix_http_proxy` +* `zabbix_https_proxy` + +# Dependencies + +The java gateway can be installed on either the zabbix-server or the zabbix-proxy machine. So one of these should be installed. You'll need to provide an parameter in your playbook for using the javagateway. + +When using the zabbix-server: +```yaml + roles: + - role: community.zabbix.zabbix_server + zabbix_server_javagateway: 192.168.1.2 +``` + +or when using the zabbix-proxy: +```yaml + roles: + - role: community.zabbix.zabbix_proxy + zabbix_proxy_server: 192.168.1.1 + zabbix_proxy_javagateway: 192.168.1.2 +``` + +# Example Playbook + +Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too: + +```yaml + - hosts: zabbix-server + sudo: yes + roles: + - role: community.zabbix.zabbix_server + zabbix_server_javagateway: 192.168.1.2 + - role: community.zabbix.zabbix_javagateway +``` + +# Molecule + +This role is configured to be tested with Molecule. You can find on this page some more information regarding Molecule: + +* http://werner-dijkerman.nl/2016/07/10/testing-ansible-roles-with-molecule-testinfra-and-docker/ +* http://werner-dijkerman.nl/2016/07/27/extending-ansible-role-testing-with-molecule-by-adding-group_vars-dependencies-and-using-travis-ci/ +* http://werner-dijkerman.nl/2016/07/31/testing-ansible-roles-in-a-cluster-setup-with-docker-and-molecule/ + +With each Pull Request, Molecule will be executed via travis.ci. Pull Requests will only be merged once these tests run successfully. + +# License + +GNU General Public License v3.0 or later + +See LICENCE to see the full text. + +# Author Information + +Please send suggestion or pull requests to make this role better. Also let us know if you encounter any issues installing or using this role. + +Github: https://github.com/ansible-collections/community.zabbix diff --git a/ansible_collections/community/zabbix/docs/ZABBIX_PROXY_ROLE.md b/ansible_collections/community/zabbix/docs/ZABBIX_PROXY_ROLE.md new file mode 100644 index 000000000..6682f6c18 --- /dev/null +++ b/ansible_collections/community/zabbix/docs/ZABBIX_PROXY_ROLE.md @@ -0,0 +1,387 @@ +# community.zabbix.zabbix_proxy role + + + +**Table of Contents** + +- [Overview](#overview) + * [Operating systems](#operating-systems) + * [Zabbix Versions](#zabbix-versions) +- [Role Variables](#role-variables) + * [Main variables](#main-variables) + + [Overall Zabbix](#overall-zabbix) + + [SElinux](#selinux) + + [Zabbix Proxy](#zabbix-proxy) + + [Database specific](#database-specific) + + [TLS Specific configuration](#tls-specific-configuration) + * [proxy](#proxy) + * [Database](#database) + + [MySQL](#mysql) + - [Local Setup](#local-setup) + - [Separate Setup](#separate-setup) + + [PostgreSQL](#postgresql) + - [Local Setup](#local-setup-1) + - [Separate Setup](#separate-setup-1) + + [SQLite3](#sqlite3) + * [Zabbix API variables](#zabbix-api-variables) +- [Example Playbook](#example-playbook) +- [Molecule](#molecule) +- [License](#license) +- [Author Information](#author-information) + +# Overview + +## Operating systems + +This role will work on the following operating systems: + + * Red Hat + * Debian + * Ubuntu + +So, you'll need one of those operating systems.. :-) +Please send Pull Requests or suggestions when you want to use this role for other Operating systems. + +# Requirements +## Ansible 2.10 and higher + +With the release of Ansible 2.10, modules have been moved into collections. With the exception of ansible.builtin modules, this means additonal collections must be installed in order to use modules such as seboolean (now ansible.posix.seboolean). The following collection is now required: `ansible.posix`. Installing the collection: + +```sh +ansible-galaxy collection install ansible.posix +``` + +If you are willing to create proxy in Zabbix via API as a part of this role execution then you need to install `ansible.netcommon` collection too: + +``` +ansible-galaxy collection install ansible.netcommon +``` + +### MySQL + +When you are a MySQL user and using Ansible 2.10 or newer, then there is a dependency on the collection named `community.mysql`. This collections are needed as the `mysql_` modules are now part of collections and not standard in Ansible anymmore. Installing the collection: + +```sh +ansible-galaxy collection install community.mysql +``` + +### PostgreSQL + +When you are a PostgreSQL user and using Ansible 2.10 or newer, then there is a dependency on the collection named `community.postgresql`. This collections are needed as the `postgresql_` modules are now part of collections and not standard in Ansible anymmore. Installing the collection: + +```sh +ansible-galaxy collection install community.postgresql +``` + +## Zabbix Versions + +See the following list of supported Operating systems with the Zabbix releases. + +| Zabbix | 6.4 | 6.2 | 6.0 | 5.4 | 5.2 | 5.0 (LTS)| 4.4 | 4.0 (LTS) | 3.0 (LTS) | +|---------------------|-----|-----|-----|-----|-----|-----------|-----|-----------|-----------| +| Red Hat Fam 9 | V | V | V | | | | | | | +| Red Hat Fam 8 | V | V | V | V | V | V | V | | | +| Red Hat Fam 7 | V | V | V | V | V | V | V | V | V | +| Red Hat Fam 6 | | | | | V | V | | | V | +| Red Hat Fam 5 | | | | | V | V | | | V | +| Fedora | | | | | | | V | V | | +| Ubuntu 20.04 focal | V | V | V | V | V | V | | V | | +| Ubuntu 18.04 bionic | | | V | V | V | V | V | V | | +| Ubuntu 16.04 xenial | | | | | V | V | V | V | | +| Ubuntu 14.04 trusty | | | | | V | V | V | V | V | +| Debian 10 buster | V | | V | V | V | V | V | | | +| Debian 9 stretch | V | | V | V | V | V | V | V | | +| Debian 8 jessie | | | | | V | V | V | V | V | +| Debian 7 wheezy | | | | | | | | V | V | +| macOS 10.15 | | | | | | | V | V | | +| macOS 10.14 | | | | | | | V | V | | + +# Role Variables + +## Main variables + +The following is an overview of all available configuration default for this role. + +### Overall Zabbix + +* `zabbix_proxy_version`: This is the version of zabbix. Default: The highest supported version for the operating system. Can be overridden to 6.2, 6.0, 5.4, 5.2, 5.0, 4.4, 4.0, 3.4, 3.2, 3.0, 2.4, or 2.2. Previously the variable `zabbix_version` was used directly but it could cause [some inconvenience](https://github.com/dj-wasabi/ansible-zabbix-agent/pull/303). That variable is maintained by retrocompativility. +* `zabbix_proxy_version_minor`: When you want to specify a minor version to be installed. RedHat only. Default set to: `*` (latest available) +* `zabbix_repo`: Default: `zabbix` + * `epel`: install agent from EPEL repo + * `zabbix`: (default) install agent from Zabbix repo + * `other`: install agent from pre-existing or other repo +* `zabbix_repo_yum`: A list with Yum repository configuration. +* `zabbix_repo_yum_schema`: Default: `https`. Option to change the web schema for the yum repository(http/https) +* `zabbix_repo_yum_disabled`: A string with repository names that should be disabled when installing Zabbix component specific packages. Is only used when `zabbix_repo_yum_enabled` contains 1 or more repositories. Default `*`. +* `zabbix_repo_yum_enabled`: A list with repository names that should be enabled when installing Zabbix component specific packages. + +### SElinux + +* `zabbix_selinux`: Default: `False`. Enables an SELinux policy so that the Proxy will run. + +### Zabbix Proxy + +* `zabbix_proxy_ip`: The IP address of the host. When not provided, it will be determined via the `ansible_default_ipv4` fact. +* `zabbix_proxy_server`: The ip or dns name for the zabbix-server machine. +* `zabbix_proxy_serverport`: The port on which the zabbix-server is running. Default: 10051 +* `*zabbix_proxy_package_state`: Default: `present`. Can be overridden to `latest` to update packages +* `zabbix_proxy_install_database_client`: Default: `True`. False does not install database client. +* `zabbix_proxy_become_on_localhost`: Default: `True`. Set to `False` if you don't need to elevate privileges on localhost to install packages locally with pip. +* `zabbix_proxy_manage_service`: Default: `True`. When you run multiple Zabbix proxies in a High Available cluster setup (e.g. pacemaker), you don't want Ansible to manage the zabbix-proxy service, because Pacemaker is in control of zabbix-proxy service. +* `zabbix_install_pip_packages`: Default: `True`. Set to `False` if you don't want to install the required pip packages. Useful when you control your environment completely. +* `zabbix_proxy_startpreprocessors`: Number of pre-forked instances of preprocessing workers. The preprocessing manager process is automatically started when a preprocessor worker is started.This parameter is supported since Zabbix 4.2.0. +* `zabbix_proxy_username`: Default: `zabbix`. The name of the account on the host. Will only be used when `zabbix_repo: epel` is used. +* `zabbix_proxy_logtype`: Specifies where log messages are written to: system, file, console. +* `zabbix_proxy_logfile`: Name of log file. +* `zabbix_proxy_userid`: The UID of the account on the host. Will only be used when `zabbix_repo: epel` is used. +* `zabbix_proxy_groupname`: Default: `zabbix`. The name of the group of the user on the host. Will only be used when `zabbix_repo: epel` is used. +* `zabbix_proxy_groupid`: The GID of the group on the host. Will only be used when `zabbix_repo: epel` is used. +* `zabbix_proxy_include_mode`: Default: `0755`. The "mode" for the directory configured with `zabbix_proxy_include`. +* `zabbix_proxy_conf_mode`: Default: `0644`. The "mode" for the Zabbix configuration file. +* `zabbix_proxy_statsallowedip`: Default: `127.0.0.1`. Allowed IP foe remote gathering of the ZabbixPorixy internal metrics. +* `zabbix_proxy_vaulttoken`: Vault authentication token that should have been generated exclusively for Zabbix server with read only permission +* `zabbix_proxy_vaulturl`: Vault server HTTP[S] URL. System-wide CA certificates directory will be used if SSLCALocation is not specified. +* `zabbix_proxy_vaultdbpath`: Vault path from where credentials for database will be retrieved by keys 'password' and 'username'. +* `zabbix_proxy_listenbacklog`: The maximum number of pending connections in the queue. + +### Database specific + +* `zabbix_proxy_dbhost_run_install`: Default: `True`. When set to `True`, sql files will be executed on the host running the database. +* `zabbix_proxy_database`: Default: `mysql`. The type of database used. Can be: `mysql`, `pgsql` or `sqlite3` +* `zabbix_proxy_database_long`: Default: `mysql`. The type of database used, but long name. Can be: `mysql`, `postgresql` or `sqlite3` +* `zabbix_proxy_dbhost`: The hostname on which the database is running. Will be ignored when `sqlite3` is used as database. +* `zabbix_proxy_real_dbhost`: The hostname of the dbhost that is running behind a loadbalancer/VIP (loadbalancers doesn't accept ssh connections) Will be ignored when `sqlite3` is used as database. +* `zabbix_proxy_dbname`: The database name which is used by the Zabbix Proxy. +* `zabbix_proxy_dbuser`: The database username which is used by the Zabbix Proxy. Will be ignored when `sqlite3` is used as database. +* `zabbix_proxy_dbpassword`: The database user password which is used by the Zabbix Proxy. Will be ignored when `sqlite3` is used as database. +* `zabbix_proxy_dbport`: The database port which is used by the Zabbix Proxy. Will be ignored when `sqlite3` is used as database. +* `zabbix_database_creation`: Default: `True`. When you don't want to create the database including user, you can set it to False. +* `zabbix_proxy_install_database_client`: Default: `True`. False does not install database client. Default true +* `zabbix_database_sqlload`:True / False. When you don't want to load the sql files into the database, you can set it to False. +* `zabbix_proxy_dbencoding`: Default: `utf8`. The encoding for the MySQL database. +* `zabbix_proxy_dbcollation`: Default: `utf8_bin`. The collation for the MySQL database.zabbix_proxy_ +* `zabbix_server_allowunsupporteddbversions`: Allow proxy to work with unsupported database versions. +* `zabbix_proxy_dbpassword_hash_method`: Default: `md5`. Allow switching postgresql user password creation to `scram-sha-256`, when anything other than `md5` is used then ansible won't hash the password with `md5`. + +### TLS Specific configuration + +These variables are specific for Zabbix 3.0 and higher: + +* `zabbix_proxy_tlsconnect`: How the agent should connect to server or proxy. Used for active checks. + Possible values: + * unencrypted + * psk + * cert +* `zabbix_proxy_tlsaccept`: What incoming connections to accept. + Possible values: + * unencrypted + * psk + * cert +* `zabbix_proxy_tlscafile`: Full pathname of a file containing the top-level CA(s) certificates for peer certificate verification. +* `zabbix_proxy_tlscrlfile`: Full pathname of a file containing revoked certificates. +* `zabbix_proxy_tlsservercertissuer`: Allowed server certificate issuer. +* `zabbix_proxy_tlsservercertsubject`: Allowed server certificate subject. +* `zabbix_proxy_tlscertfile`: Full pathname of a file containing the agent certificate or certificate chain. +* `zabbix_proxy_tlskeyfile`: Full pathname of a file containing the agent private key. +* `zabbix_proxy_dbtlsconnect`: Setting this option enforces to use TLS connection to database: + +`required` - connect using TLS +`verify_ca` - connect using TLS and verify certificate +`verify_full` - connect using TLS, verify certificate and verify that database identity specified by DBHost matches its certificate + +On `MySQL` starting from 5.7.11 and `PostgreSQL` the following values are supported: `required`, `verify`, `verify_full`. On MariaDB starting from version 10.2.6 `required` and `verify_full` values are supported. +By default not set to any option and the behaviour depends on database configuration. +This parameter is supported since Zabbix 5.0.0. + +* `zabbix_proxy_dbtlscafile`: Full pathname of a file containing the top-level CA(s) certificates for database certificate verification. This parameter is supported since Zabbix 5.0.0. +* `zabbix_proxy_dbtlscertfile`: Full pathname of file containing Zabbix Proxy certificate for authenticating to database. This parameter is supported since Zabbix 5.0.0. +* `zabbix_proxy_dbtlskeyfile`: Full pathname of file containing the private key for authenticating to database. This parameter is supported since Zabbix 5.0.0. +* `zabbix_proxy_dbtlscipher`: The list of encryption ciphers that Zabbix Proxy permits for TLS protocols up through TLSv1.2. Supported only for MySQL.This parameter is supported since Zabbix 5.0.0. +* `zabbix_proxy_dbtlscipher13`: The list of encryption ciphersuites that Zabbix Proxy permits for TLSv1.3 protocol. Supported only for MySQL, starting from version 8.0.16. This parameter is supported since Zabbix 5.0.0. + +## proxy + +When the target host does not have access to the internet, but you do have a proxy available then the following properties needs to be set to download the packages via the proxy: + +* `zabbix_http_proxy` +* `zabbix_https_proxy` + +## Database + +With Zabbix Proxy you can make use of 2 different databases: + +* `mysql` +* `postgresql` +* `SQLite3` + +In the following paragraphs we dive into both setups. + +### MySQL + +To make the Zabbix Proxy work with a `MySQL` database, there are 2 types on setup: + +1. Local setup, `MySQL` running on same host as the Zabbix Proxy; +2. Separate setup, `MySQL` running on a different host than the Zabbix Proxy. + +#### Local Setup + +We need to have the following dependencies met: + +1. Find an (Ansible) role that will install a `MySQL` instance on the host. Example: `geerlingguy.mysql` can be used, but also others can be used. Please make sure that before installing the Zabbix Proxy, you have a fully functional `MySQL` instance running. +2. We need to set some variables, either as input for the playbook or set them into the `group_vars` or `host_vars` (Your preference choice). We need to set the following properties: + +```yaml +zabbix_proxy_database: mysql +zabbix_proxy_database_long: mysql +zabbix_proxy_dbport: 3306 +zabbix_proxy_dbpassword: <SOME_SECRET_STRING> +``` + +Please generate a value for the `zabbix_proxy_dbpassword` property (Maybe use `ansible-vault` for this). The zabbix-proxy role will create an database and username (With the provided value for the password) in `MySQL`. +3. Execute the role by running the Ansible playbook that calls this role. At the end of this run, the Zabbix Proxy with `MySQL` will be running. + +#### Separate Setup + +We need to have the following dependencies met: + +1. We need to either have a `MySQL` instance running somewhere in the environment. If this is the case, we need to have a username/password combination that is allowed to create a database and an user account. If there isn't one, please make sure there is one. +2. We need to set some variables, either as input for the playbook or set them into the `group_vars` or `host_vars` (Your preference choice). We need to set the following properties: + +```yaml +zabbix_proxy_database: mysql +zabbix_proxy_database_long: mysql +zabbix_proxy_dbport: 3306 +zabbix_proxy_dbhost: mysql-host +zabbix_proxy_dbhost_run_install: false +zabbix_proxy_dbpassword: <SOME_SECRET_STRING> +zabbix_proxy_privileged_host: '%' +zabbix_proxy_mysql_login_host: mysql-host +zabbix_proxy_mysql_login_user: root +zabbix_proxy_mysql_login_password: changeme +zabbix_proxy_mysql_login_port: 3306 +``` + +Please generate a value for the `zabbix_proxy_dbpassword` property (Maybe use `ansible-vault` for this). The zabbix-proxy role will create an database and username (With the provided value for the password) in `MySQL`. + +The `zabbix_proxy_privileged_host` can be set to the hostname/ip of the host running Zabbix Proxy for security related purposes. Also make sure that `zabbix_proxy_mysql_login_password` is set to the correct password for the user provided with `zabbix_proxy_mysql_login_host` to create a database and user in the `MySQL` instance. + +3. Execute the role by running the Ansible playbook that calls this role. At the end of this run, the Zabbix Proxy with `MySQL` on a different host will be running. + +### PostgreSQL + +To make the Zabbix Proxy work with a `PgSQL` database, there are 2 types on setup: + +1. Local setup, `PgSQL` running on same host as the Zabbix Proxy; +2. Separate setup, `PgSQL` running on a different host than the Zabbix Proxy. + +#### Local Setup + +We need to have the following dependencies met: + +1. Find an (Ansible) role that will install a `PgSQL` instance on the host. Example: `geerlingguy.postgresql` can be used, but also others can be used. Please make sure that before installing the Zabbix Proxy, you have a fully functional `PgSQL` instance running. +2. We need to set some variables, either as input for the playbook or set them into the `group_vars` or `host_vars` (Your preference choice). We need to set the following properties: + +```yaml +zabbix_proxy_database: pgsql +zabbix_proxy_database_long: postgresql +zabbix_proxy_dbport: 5432 +zabbix_proxy_dbpassword: <SOME_SECRET_STRING> +``` + +Please generate a value for the `zabbix_proxy_dbpassword` property (Maybe use `ansible-vault` for this). The zabbix-proxy role will create an database and username (With the provided value for the password) in `PgSQL`. +3. Execute the role by running the Ansible playbook that calls this role. At the end of this run, the Zabbix Proxy with `PgSQL` will be running. + +#### Separate Setup + +We need to have the following dependencies met: + +1. We need to either have a `PgSQL` instance running somewhere in the environment. If this is the case, we need to have a username/password combination that is allowed to create a database and an user account. If there isn't one, please make sure there is one. +2. We need to set some variables, either as input for the playbook or set them into the `group_vars` or `host_vars` (Your preference choice). We need to set the following properties: + +```yaml +zabbix_proxy_database: pgsql +zabbix_proxy_database_long: postgresql +zabbix_proxy_dbport: 5432 +zabbix_proxy_dbhost: pgsql-host +zabbix_proxy_dbhost_run_install: false +zabbix_proxy_dbpassword: <SOME_SECRET_STRING> +zabbix_proxy_privileged_host: '%' +zabbix_proxy_pgsql_login_host: pgsql-host +zabbix_proxy_pgsql_login_user: postgres +zabbix_proxy_pgsql_login_password: changeme +zabbix_proxy_pgsql_login_port: 5432 +``` + +Please generate a value for the `zabbix_proxy_dbpassword` property (Maybe use `ansible-vault` for this). The zabbix-proxy role will create an database and username (With the provided value for the password) in `PgSQL`. + +The `zabbix_proxy_privileged_host` can be set to the hostname/ip of the host running Zabbix Proxy for security related purposes. Also make sure that `zabbix_proxy_mysql_login_password` is set to the correct password for the user provided with `zabbix_proxy_mysql_login_host` to create a database and user in the `PgSQL` instance. + +3. Execute the role by running the Ansible playbook that calls this role. At the end of this run, the Zabbix Proxy with `PgSQL` on a different host will be running.zabbix_proxy_ + +### SQLite3 + +The SQLite3 can only be used on the same host as on which the Zabbix Proxy is running. If you want to use a seperate host for running the database for the proxy, please consider going for MySQL or PostGreSQL. + +The following properties needs to be set when using `SQLite3` as the database: + +```yaml +zabbix_proxy_database: sqlite3 +zabbix_proxy_database_long: sqlite3 +zabbix_proxy_dbname: /path/to/sqlite3.db +``` + +NOTE: When using `zabbix_proxy_dbname: zabbix_proxy` (Which is default with this role), it will automatically be stored on `/var/lib/zabbix/zabbix_proxy.db` + +## Zabbix API variables + +These variables need to be overridden when you want to make use of the Zabbix API for automatically creating and or updating proxies, i.e. when `zabbix_api_create_proxy` is set to `True`. + +* `zabbix_api_http_user`: The http user to access zabbix url with Basic Auth. +* `zabbix_api_http_password`: The http password to access zabbix url with Basic Auth. +* `zabbix_api_server_host`: The IP or hostname/FQDN of Zabbix server. Example: zabbix.example.com +* `zabbix_api_server_port`: TCP port to use to connect to Zabbix server. Example: 8080 +* `zabbix_api_use_ssl`: yes (Default) if we need to connect to Zabbix server over HTTPS +* `zabbix_api_validate_certs` : yes (Default) if we need to validate tls certificates of the API. Use `no` in case self-signed certificates are used +* `zabbix_api_login_user`: Username of user which has API access. +* `zabbix_api_login_pass`: Password for the user which has API access. +* `ansible_zabbix_url_path`: URL path if Zabbix WebUI running on non-default (zabbix) path, e.g. if http://<FQDN>/zabbixeu then set to `zabbixeu` +* `zabbix_api_create_proxy`: When you want to enable the Zabbix API to create/delete the proxy. This has to be set to `True` if you want to make use of `zabbix_proxy_state`. Default: `False` +* `zabbix_proxy_name`: name of the Zabbix proxy as it is seen by Zabbix server +* `zabbix_proxy_state`: present (Default) if the proxy needs to be created or absent if you want to delete it. This only works when `zabbix_api_create_proxy` is set to `True`. +* `zabbix_proxy_status`: active (Default) if the proxy needs to be active or passive. +* `zabbix_api_timeout`: timeout for API calls (default to 30 seconds) + +# Example Playbook + +Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too: + +```yaml + - hosts: zabbix-proxy + roles: + - role: community.zabbix.zabbix_proxy + zabbix_proxy_server: 192.168.1.1 + zabbix_proxy_database: mysql + zabbix_proxy_database_long: mysql +``` + +# Molecule + +This role is configured to be tested with Molecule. You can find on this page some more information regarding Molecule: + +* http://werner-dijkerman.nl/2016/07/10/testing-ansible-roles-with-molecule-testinfra-and-docker/ +* http://werner-dijkerman.nl/2016/07/27/extending-ansible-role-testing-with-molecule-by-adding-group_vars-dependencies-and-using-travis-ci/ +* http://werner-dijkerman.nl/2016/07/31/testing-ansible-roles-in-a-cluster-setup-with-docker-and-molecule/ + +With each Pull Request, Molecule will be executed via travis.ci. Pull Requests will only be merged once these tests run successfully. + +# License + +GNU General Public License v3.0 or later + +See LICENCE to see the full text. + +# Author Information + +Please send suggestion or pull requests to make this role better. Also let us know if you encounter any issues installing or using this role. + +Github: https://github.com/ansible-collections/community.zabbix diff --git a/ansible_collections/community/zabbix/docs/ZABBIX_SERVER_ROLE.md b/ansible_collections/community/zabbix/docs/ZABBIX_SERVER_ROLE.md new file mode 100644 index 000000000..4643fbc3f --- /dev/null +++ b/ansible_collections/community/zabbix/docs/ZABBIX_SERVER_ROLE.md @@ -0,0 +1,385 @@ +# community.zabbix.zabbix_server role + + + +**Table of Contents** + +- [Overview](#overview) +- [Requirements](#requirements) + * [Operating systems](#operating-systems) + * [Zabbix Versions](#zabbix-versions) +- [Installation](#installation) +- [Role Variables](#role-variables) + * [Main variables](#main-variables) + + [Overall Zabbix](#overall-zabbix) + + [SElinux](#selinux) + + [Zabbix Server](#zabbix-server) + + [Database specific](#database-specific) + + [TLS Specific configuration](#tls-specific-configuration) + + [Custom Zabbix Scripts](#custom-zabbix-scripts) + * [proxy](#proxy) + * [Database](#database) + + [MySQL](#mysql) + - [Local Setup](#local-setup) + - [Separate Setup](#separate-setup) + + [PostgreSQL](#postgresql) + - [Local Setup](#local-setup-1) + - [Separate Setup](#separate-setup-1) +- [Example Playbook](#example-playbook) +- [Molecule](#molecule) +- [License](#license) +- [Author Information](#author-information) + +# Overview + +This is a Ansible role for installing and maintaining the zabbix-server. This will only install the Zabbix Server component and not the Zabbix Web. + +# Requirements + +## Operating systems + +This role will work on the following operating systems: + + * Red Hat + * Debian + * Ubuntu + +So, you'll need one of those operating systems.. :-) +Please send Pull Requests or suggestions when you want to use this role for other Operating systems. + +## Ansible 2.10 and higher + +With the release of Ansible 2.10, modules have been moved into collections. With the exception of ansible.builtin modules, this means additonal collections must be installed in order to use modules such as seboolean (now ansible.posix.seboolean). The following collection is now required: `ansible.posix`. Installing the collection: + +```sh +ansible-galaxy collection install ansible.posix +``` + +### MySQL + +When you are a MySQL user and using Ansible 2.10 or newer, then there is a dependency on the collection named `community.mysql`. This collections are needed as the `mysql_` modules are now part of collections and not standard in Ansible anymmore. Installing the collection: + +```sh +ansible-galaxy collection install community.mysql +``` + +### PostgreSQL + +When you are a PostgreSQL user and using Ansible 2.10 or newer, then there is a dependency on the collection named `community.postgresql`. This collections are needed as the `postgresql_` modules are now part of collections and not standard in Ansible anymmore. Installing the collection: + +```sh +ansible-galaxy collection install community.postgresql +``` + +## Zabbix Versions + +See the following list of supported Operating systems with the Zabbix releases: + +| Zabbix | 6.4 | 6.2 | 6.0 | 5.4 | 5.2 | 5.0 (LTS) | 4.4 | 4.0 (LTS) | 3.0 (LTS) | +|---------------------|-----|-----|-----|-----|-----|-----------|-----|-----------|-----------| +| Red Hat Fam 9 | V | V | V | | | | | | | +| Red Hat Fam 8 | V | V | V | V | V | V | V | | | +| Red Hat Fam 7 | | | | | | V | V | V | V | +| Red Hat Fam 6 | | | | | V | V | | | V | +| Red Hat Fam 5 | | | | | V | V | | | V | +| Fedora | | | | | | | V | V | | +| Ubuntu 20.04 focal | V | V | V | V | V | V | | V | | +| Ubuntu 18.04 bionic | | | V | V | V | V | V | V | | +| Ubuntu 16.04 xenial | | | | | V | V | V | V | | +| Ubuntu 14.04 trusty | | | | | V | V | V | V | V | +| Debian 10 buster | | | V | V | V | V | V | | | +| Debian 9 stretch | | | V | V | V | V | V | V | | +| Debian 8 jessie | | | | | V | V | V | V | V | +| Debian 7 wheezy | | | | | | | | V | V | +| macOS 10.15 | | | | | | | V | V | | +| macOS 10.14 | | | | | | | V | V | | + +See https://support.zabbix.com/browse/ZBX-18790 why RHEL7 is not supported anymore. + +# Installation + +Installing this role is very simple: `ansible-galaxy install community.zabbix.zabbix_server` + +Please be aware that this role only installs the Zabbix Server and not the Zabbix Web. If you do want to have a Zabbix Web, please execute the following command: `ansible-galaxy install community.zabbix.zabbix_web` + +# Role Variables + +## Main variables + +The following is an overview of all available configuration default for this role. + +### Overall Zabbix + +* `zabbix_server_version`: This is the version of zabbix. Default: The highest supported version for the operating system. Can be overridden to 6.2, 6.0, 5.4, 5.2, 5.0, 4.4, 4.0, 3.4, 3.2, 3.0, 2.4, or 2.2. Previously the variable `zabbix_version` was used directly but it could cause [some inconvenience](https://github.com/dj-wasabi/ansible-zabbix-agent/pull/303). That variable is maintained by retrocompativility. +* `zabbix_server_version_minor`: When you want to specify a minor version to be installed. RedHat only. Default set to: `*` (latest available) +* `zabbix_repo`: Default: `zabbix` + * `epel`: install agent from EPEL repo + * `zabbix`: (default) install agent from Zabbix repo + * `other`: install agent from pre-existing or other repo +* `zabbix_repo_yum`: A list with Yum repository configuration. +* `zabbix_repo_yum_schema`: Default: `https`. Option to change the web schema for the yum repository(http/https) +* `zabbix_repo_yum_disabled`: A string with repository names that should be disabled when installing Zabbix component specific packages. Is only used when `zabbix_repo_yum_enabled` contains 1 or more repositories. Default `*`. +* `zabbix_repo_yum_enabled`: A list with repository names that should be enabled when installing Zabbix component specific packages. +* `zabbix_service_state`: Default: `started`. Can be overridden to stopped if needed +* `zabbix_service_enabled`: Default: `True` Can be overridden to `False` if needed + +### SElinux + +* `zabbix_selinux`: Default: `False`. Enables an SELinux policy so that the server will run. +* `selinux_allow_zabbix_can_network`: Default: `False`. +* `selinux_allow_zabbix_can_http`: Default: `False`. + +### Zabbix Server + +* `zabbix_server_package_state`: Default: `present`. Can be overridden to `latest` to update packages when needed. +* `zabbix_server_listenport`: Default: `10051`. On which port the Zabbix Server is available. +* `zabbix_server_install_recommends`: Default: `True`. `False` does not install the recommended packages that come with the zabbix-server install. +* `zabbix_server_manage_service`: Default: `True`. When you run multiple Zabbix servers in a High Available cluster setup (e.g. pacemaker), you don't want Ansible to manage the zabbix-server service, because Pacemaker is in control of zabbix-server service and in this case, it needs to be set to `False`. +* `zabbix_proxy_startpreprocessors`: Number of pre-forked instances of preprocessing workers. The preprocessing manager process is automatically started when a preprocessor worker is started. This parameter is supported since Zabbix 4.2.0. +* `zabbix_server_username`: Default: `zabbix`. The name of the account on the host. Will only be used when `zabbix_repo: epel` is used. +* `zabbix_server_userid`: The UID of the account on the host. Will only be used when `zabbix_repo: epel` is used. +* `zabbix_server_groupname`: Default: `zabbix`. The name of the group of the user on the host. Will only be used when `zabbix_repo: epel` is used. +* `zabbix_server_groupid`: The GID of the group on the host. Will only be used when `zabbix_repo: epel` is used. +* `zabbix_server_include_mode`: Default: `0755`. The "mode" for the directory configured with `zabbix_server_include`. +* `zabbix_server_conf_mode`: Default: `0640`. The "mode" for the Zabbix configuration file. +* `zabbix_server_listenbacklog`: The maximum number of pending connections in the queue. +* `zabbix_server_trendcachesize`: Size of trend cache, in bytes. +* `zabbix_server_trendfunctioncachesize`: Size of trend function cache, in bytes. +* `zabbix_server_vaulttoken`: Vault authentication token that should have been generated exclusively for Zabbix server with read only permission +* `zabbix_server_vaulturl`: Vault server HTTP[S] URL. System-wide CA certificates directory will be used if SSLCALocation is not specified. +* `zabbix_server_vaultdbpath`: Vault path from where credentials for database will be retrieved by keys 'password' and 'username'. +* `zabbix_server_startreportwriters`: Number of pre-forked report writer instances. +* `zabbix_server_webserviceurl`: URL to Zabbix web service, used to perform web related tasks. +* `zabbix_server_servicemanagersyncfrequency`: How often Zabbix will synchronize configuration of a service manager (in seconds). +* `zabbix_server_problemhousekeepingfrequency`: How often Zabbix will delete problems for deleted triggers (in seconds). +* `zabbix_server_connectors`: Number of pre-forked instances of preprocessing workers. + +### High Availability + +These variables are specific for Zabbix 6.0 and higher: + +* `zabbix_server_hanodename`: The high availability cluster node name. When empty, server is working in standalone mode; a node with empty name is registered with address for the frontend to connect to. (Default: empty) +* `zabbix_server_nodeaddress`: IP or hostname with optional port to specify how frontend should connect to the server. + +### Database specific + +* `zabbix_server_dbhost_run_install`: Default: `True`. When set to `True`, sql files will be executed on the host running the database. +* `zabbix_server_database`: Default: `pgsql`. The type of database used. Can be: `mysql` or `pgsql` +* `zabbix_server_database_long`: Default: `postgresql`. The type of database used, but long name. Can be: `mysql` or `postgresql` +* `zabbix_server_dbhost`: The hostname on which the database is running. +* `zabbix_server_real_dbhost`: The hostname of the dbhost that is running behind a loadbalancer/VIP (loadbalancers doesn't accept ssh connections) +* `zabbix_server_dbname`: The database name which is used by the Zabbix Server. +* `zabbix_server_dbuser`: The database username which is used by the Zabbix Server. +* `zabbix_server_dbpassword`: The database user password which is used by the Zabbix Server. +* `zabbix_server_dbport`: The database port which is used by the Zabbix Server. +* `zabbix_server_dbpassword_hash_method`: Default: `md5`. Allow switching postgresql user password creation to `scram-sha-256`, when anything other than `md5` is used then ansible won't hash the password with `md5`. +* `zabbix_database_creation`: Default: `True`. When you don't want to create the database including user, you can set it to False. +* `zabbix_server_install_database_client`: Default: `True`. False does not install database client. Default true +* `zabbix_database_sqlload`:True / False. When you don't want to load the sql files into the database, you can set it to False. +* `zabbix_database_timescaledb`:False / True. When you want to use timescaledb extension into the database, you can set it to True (this option only works for postgreSQL database). +* `zabbix_server_dbencoding`: Default: `utf8`. The encoding for the MySQL database. +* `zabbix_server_dbcollation`: Default: `utf8_bin`. The collation for the MySQL database. +* `zabbix_server_allowunsupporteddbversions`: Allow server to work with unsupported database versions. + +### TLS Specific configuration + +These variables are specific for Zabbix 3.0 and higher: + +* `zabbix_server_tlsconnect`: How the agent should connect to server or proxy. Used for active checks. + Possible values: + * unencrypted + * psk + * cert +* `zabbix_server_tlsaccept`: What incoming connections to accept. + Possible values: + * unencrypted + * psk + * cert +* `zabbix_server_tlscafile`: Full pathname of a file containing the top-level CA(s) certificates for peer certificate verification. +* `zabbix_server_tlscrlfile`: Full pathname of a file containing revoked certificates. +* `zabbix_server_tlsservercertissuer`: Allowed server certificate issuer. +* `zabbix_server_tlsservercertsubject`: Allowed server certificate subject. +* `zabbix_server_tlscertfile`: Full pathname of a file containing the agent certificate or certificate chain. +* `zabbix_server_tlskeyfile`: Full pathname of a file containing the agent private key. +* `zabbix_server_dbtlsconnect`: Setting this option enforces to use TLS connection to database: + +`required` - connect using TLS +`verify_ca` - connect using TLS and verify certificate +`verify_full` - connect using TLS, verify certificate and verify that database identity specified by DBHost matches its certificate + +On `MySQL` starting from 5.7.11 and `PostgreSQL` the following values are supported: `required`, `verify`, `verify_full`. On MariaDB starting from version 10.2.6 `required` and `verify_full` values are supported. +By default not set to any option and the behaviour depends on database configuration. +This parameter is supported since Zabbix 5.0.0. + +* `zabbix_server_dbtlscafile`: Full pathname of a file containing the top-level CA(s) certificates for database certificate verification. This parameter is supported since Zabbix 5.0.0. +* `zabbix_server_dbtlscertfile`: Full pathname of file containing Zabbix server certificate for authenticating to database. This parameter is supported since Zabbix 5.0.0. +* `zabbix_server_dbtlskeyfile`: Full pathname of file containing the private key for authenticating to database. This parameter is supported since Zabbix 5.0.0. +* `zabbix_server_dbtlscipher`: The list of encryption ciphers that Zabbix server permits for TLS protocols up through TLSv1.2. Supported only for MySQL.This parameter is supported since Zabbix 5.0.0. +* `zabbix_server_dbtlscipher13`: The list of encryption ciphersuites that Zabbix server permits for TLSv1.3 protocol. Supported only for MySQL, starting from version 8.0.16. This parameter is supported since Zabbix 5.0.0. + +### Custom Zabbix Scripts + +Define these variables to copy scripts to your respective scripts path. + +* `zabbix_server_alertscripts`: List of alertscripts to be added to `zabbix_server_alertscriptspath` +* `zabbix_server_externalscripts`: List of alertscripts to be added to `zabbix_server_externalscriptspath` + +Example: + +```yaml + zabbix_server_alertscripts: + - path: "{{ lookup('first_found', 'zabbix-scripts/somescript.php') }}" + name: "somescript.php" +``` + +## proxy + +When the target host does not have access to the internet, but you do have a proxy available then the following properties needs to be set to download the packages via the proxy: + +* `zabbix_http_proxy` +* `zabbix_https_proxy` + +## Database + +With Zabbix Server you can make use of 2 different databases: + +* `mysql` +* `postgresql` + +In the following paragraphs we dive into both setups. + +### MySQL + +To make the Zabbix Server work with a `MySQL` database, there are 2 types on setup: + +1. Local setup, `MySQL` running on same host as the Zabbix Server; +2. Separate setup, `MySQL` running on a different host than the Zabbix Server. + +#### Local Setup + +We need to have the following dependencies met: + +1. Find an (Ansible) role that will install a `MySQL` instance on the host. Example: `geerlingguy.mysql` can be used, but also others can be used. Please make sure that before installing the Zabbix Server, you have a fully functional `MySQL` instance running. +2. We need to set some variables, either as input for the playbook or set them into the `group_vars` or `host_vars` (Your preference choice). We need to set the following properties: + +```yaml +zabbix_server_database: mysql +zabbix_server_database_long: mysql +zabbix_server_dbport: 3306 +zabbix_server_dbpassword: <SOME_SECRET_STRING> +``` + +Please generate a value for the `zabbix_server_dbpassword` property (Maybe use `ansible-vault` for this). The zabbix-server role will create an database and username (With the provided value for the password) in `MySQL`. +3. Execute the role by running the Ansible playbook that calls this role. At the end of this run, the Zabbix Server with `MySQL` will be running. + +#### Separate Setup + +We need to have the following dependencies met: + +1. We need to either have a `MySQL` instance running somewhere in the environment. If this is the case, we need to have a username/password combination that is allowed to create a database and an user account. If there isn't one, please make sure there is one. +2. We need to set some variables, either as input for the playbook or set them into the `group_vars` or `host_vars` (Your preference choice). We need to set the following properties: + +```yaml +zabbix_server_database: mysql +zabbix_server_database_long: mysql +zabbix_server_dbport: 3306 +zabbix_server_dbhost: mysql-host +zabbix_server_dbhost_run_install: false +zabbix_server_dbpassword: <SOME_SECRET_STRING> +zabbix_server_privileged_host: '%' +zabbix_server_mysql_login_host: mysql-host +zabbix_server_mysql_login_user: root +zabbix_server_mysql_login_password: changeme +zabbix_server_mysql_login_port: 3306 +``` + +Please generate a value for the `zabbix_server_dbpassword` property (Maybe use `ansible-vault` for this). The zabbix-server role will create an database and username (With the provided value for the password) in `MySQL`. + +The `zabbix_server_privileged_host` can be set to the hostname/ip of the host running Zabbix Server for security related purposes. Also make sure that `zabbix_server_mysql_login_password` is set to the correct password for the user provided with `zabbix_server_mysql_login_host` to create a database and user in the `MySQL` instance. + +3. Execute the role by running the Ansible playbook that calls this role. At the end of this run, the Zabbix Server with `MySQL` on a different host will be running. + +### PostgreSQL + +To make the Zabbix Server work with a `PgSQL` database, there are 2 types on setup: + +1. Local setup, `PgSQL` running on same host as the Zabbix Server; +2. Separate setup, `PgSQL` running on a different host than the Zabbix Server. + +#### Local Setup + +We need to have the following dependencies met: + +1. Find an (Ansible) role that will install a `PgSQL` instance on the host. Example: `geerlingguy.postgresql` can be used, but also others can be used. Please make sure that before installing the Zabbix Server, you have a fully functional `PgSQL` instance running. +2. We need to set some variables, either as input for the playbook or set them into the `group_vars` or `host_vars` (Your preference choice). We need to set the following properties: + +```yaml +zabbix_server_database: pgsql +zabbix_server_database_long: postgresql +zabbix_server_dbport: 5432 +zabbix_server_dbpassword: <SOME_SECRET_STRING> +``` + +Please generate a value for the `zabbix_server_dbpassword` property (Maybe use `ansible-vault` for this). The zabbix-server role will create an database and username (With the provided value for the password) in `PgSQL`. Set `zabbix_server_dbpassword_hash_method` for PostgreSQL 10 and newer if they default to `scram-sha-256`. +3. Execute the role by running the Ansible playbook that calls this role. At the end of this run, the Zabbix Server with `PgSQL` will be running. + +#### Separate Setup + +We need to have the following dependencies met: + +1. We need to either have a `PgSQL` instance running somewhere in the environment. If this is the case, we need to have a username/password combination that is allowed to create a database and an user account. If there isn't one, please make sure there is one. +2. We need to set some variables, either as input for the playbook or set them into the `group_vars` or `host_vars` (Your preference choice). We need to set the following properties: + +```yaml +zabbix_server_database: pgsql; +zabbix_server_database_long: postgresql +zabbix_server_dbport: 5432 +zabbix_server_dbhost: pgsql-host +zabbix_server_dbhost_run_install: false +zabbix_server_dbpassword: <SOME_SECRET_STRING> +zabbix_server_privileged_host: '%' +zabbix_server_pgsql_login_host: pgsql-host +zabbix_server_pgsql_login_user: postgres +zabbix_server_pgsql_login_password: changeme +zabbix_server_pgsql_login_port: 5432 +``` + +Please generate a value for the `zabbix_server_dbpassword` property (Maybe use `ansible-vault` for this). The zabbix-server role will create an database and username (With the provided value for the password) in `PgSQL`. Set `zabbix_server_dbpassword_hash_methodh` for PostgreSQL 10 and newer if they default to `scram-sha-256`. + +The `zabbix_server_privileged_host` can be set to the hostname/ip of the host running Zabbix Server for security related purposes. Also make sure that `zabbix_server_mysql_login_password` is set to the correct password for the user provided with `zabbix_server_mysql_login_host` to create a database and user in the `PgSQL` instance. + +3. Execute the role by running the Ansible playbook that calls this role. At the end of this run, the Zabbix Server with `PgSQL` on a different host will be running. + +# Example Playbook + +Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too: + +```yaml + - hosts: zabbix-server + roles: + - role: community.zabbix.zabbix_server + zabbix_server_database: mysql + zabbix_server_database_long: mysql +``` + +# Molecule + +This role is configured to be tested with Molecule. You can find on this page some more information regarding Molecule: + +* http://werner-dijkerman.nl/2016/07/10/testing-ansible-roles-with-molecule-testinfra-and-docker/ +* http://werner-dijkerman.nl/2016/07/27/extending-ansible-role-testing-with-molecule-by-adding-group_vars-dependencies-and-using-travis-ci/ +* http://werner-dijkerman.nl/2016/07/31/testing-ansible-roles-in-a-cluster-setup-with-docker-and-molecule/ + +With each Pull Request, Molecule will be executed via Github Actions to validate the change on a new installation. Each PR should result into a correct working Zabbix Server installation and PR's will not be merged once this process fails. + +# License + +GNU General Public License v3.0 or later + +See LICENCE to see the full text. + +# Author Information + +Please send suggestion or pull requests to make this role better. Also let us know if you encounter any issues installing or using this role. + +Github: https://github.com/ansible-collections/community.zabbix diff --git a/ansible_collections/community/zabbix/docs/ZABBIX_WEB_ROLE.md b/ansible_collections/community/zabbix/docs/ZABBIX_WEB_ROLE.md new file mode 100644 index 000000000..cef5d62e7 --- /dev/null +++ b/ansible_collections/community/zabbix/docs/ZABBIX_WEB_ROLE.md @@ -0,0 +1,349 @@ +# community.zabbix.zabbix_web role + + + +**Table of Contents** + +- [Overview](#overview) +- [Requirements](#requirements) + - [Operating Systems](#operating-systems) + - [Zabbix Versions](#zabbix-versions) +- [Installation](#installation) +- [Role Variables](#role-variables) + - [Main variables](#main-variables) + - [Overall Zabbix](#overall-zabbix) + - [Zabbix Web specific](#zabbix-web-specific) + - [Apache configuration](#apache-configuration) + - [Nginx configuration](#nginx-configuration) + - [PHP-FPM](#php-fpm) + - [Zabbix Server](#zabbix-server) + * [proxy](#proxy) +- [Example Playbook](#example-playbook) + - [Single instance](#single-instance) + - [Multi host setup](#multi-host-setup) + - [Adding Environment Variables for zabbix_web](#adding-environment-variables-for-zabbixweb) + - [Using Elasticsearch for history storage](#using-elasticsearch-for-history-storage) +- [Molecule](#molecule) +- [License](#license) +- [Author Information](#author-information) + +# Overview + +# Requirements +## Operating Systems + +This role will work on the following operating systems: + + * RedHat + * Debian + * Ubuntu + +So, you'll need one of those operating systems.. :-) +Please send Pull Requests or suggestions when you want to use this role for other Operating systems. + +## Ansible 2.10 and higher + +With the release of Ansible 2.10, modules have been moved into collections. With the exception of ansible.builtin modules, this means additonal collections must be installed in order to use modules such as seboolean (now ansible.posix.seboolean). The following collections are now required: `ansible.posix`. The `community.general` collection is required when defining the `zabbix_web_htpasswd` variable (see variable section below). Installing the collections: + +```sh +ansible-galaxy collection install ansible.posix +ansible-galaxy collection install community.general +``` + +## Zabbix Versions + +See the following list of supported Operating Systems with the Zabbix releases. + +| Zabbix | 6.4 | 6.2 | 6.0 (LTS) | 5.4 | 5.2 | 5.0 (LTS) | 4.4 | 4.0 (LTS) | 3.0 (LTS) | +|---------------------|-----|-----|-----------|-----|-----|------------|-----|-----------|-----------| +| Red Hat Fam 9 | V | V | V | | | | | | | +| Red Hat Fam 8 | V | V | V | V | V | V | V | | | +| Red Hat Fam 7 | | V | V | V | V | V | V | V | V | +| Red Hat Fam 6 | | | | | V | V | | | V | +| Red Hat Fam 5 | | | | | V | V | | | V | +| Fedora | | | | | | | V | V | | +| Ubuntu 22.04 jammy | V | V | V | | | | | | | +| Ubuntu 20.04 focal | V | V | V | V | V | V | V | | | +| Ubuntu 18.04 bionic | | | V | V | V | V | V | V | | +| Ubuntu 16.04 xenial | | | | | V | V | V | V | | +| Ubuntu 14.04 trusty | | | | | V | V | V | V | V | +| Debian 10 buster | V | V | V | V | V | V | V | | | +| Debian 9 stretch | | | V | V | V | V | V | V | | +| Debian 8 jessie | | | | | V | V | V | V | V | +| Debian 7 wheezy | | | | | | | | V | V | +| macOS 10.15 | | | | | | | V | V | | +| macOS 10.14 | | | | | | | V | V | | + +# Installation + +Installing this role is very simple: `ansible-galaxy install community.zabbix.zabbix_web` + +When the Zabbix Web needs to be running on the same host as the Zabbix Server, please also install the Zabbix Server by executing the following command: `ansible-galaxy install community.zabbix.zabbix_server` + +Default username/password for the Zabbix Web interface is the default. + +Username: Admin +Password: zabbix + +# Role Variables + +## Main variables + +The following is an overview of all available configuration defaults for this role. + +### Overall Zabbix + +* `zabbix_web_version`: This is the version of zabbix. Default: The highest supported version for the operating system. Can be overridden to 6.2, 6.0, 5.4, 5.2, 5.0, 4.4, 4.0, 3.4, 3.2, 3.0, 2.4, or 2.2. Previously the variable `zabbix_version` was used directly but it could cause [some inconvenience](https://github.com/dj-wasabi/ansible-zabbix-agent/pull/303). That variable is maintained by retrocompativility. +* `zabbix_web_version_minor`: When you want to specify a minor version to be installed. RedHat only. Default set to: `*` (latest available) +* `zabbix_repo`: Default: `zabbix` + * `epel`: install agent from EPEL repo + * `zabbix`: (default) install agent from Zabbix repo + * `other`: install agent from pre-existing or other repo +* `zabbix_repo_yum`: A list with Yum repository configuration. +* `zabbix_repo_yum_schema`: Default: `https`. Option to change the web schema for the yum repository(http/https) +* `zabbix_repo_yum_disabled`: A string with repository names that should be disabled when installing Zabbix component specific packages. Is only used when `zabbix_repo_yum_enabled` contains 1 or more repositories. Default `*`. +* `zabbix_repo_yum_enabled`: A list with repository names that should be enabled when installing Zabbix component specific packages. + +* `zabbix_web_package_state`: Default: `present`. Can be overridden to `latest` to update packages when needed. +* `zabbix_web_centos_release`: Default: True. When the `centos-release-scl` repository needs to be enabled. This is required when using Zabbix 5.0 due to installation of a recent version of `PHP`. +* `zabbix_web_rhel_release`: Default: True. When the `scl-utils` repository needs to be enabled. This is required when using Zabbix 5.0 due to installation of a recent version of `PHP`. +* `zabbix_web_doubleprecision`: Default: `False`. For upgraded installations, please read database [upgrade notes](https://www.zabbix.com/documentation/current/manual/installation/upgrade_notes_500) (Paragraph "Enabling extended range of numeric (float) values") before enabling this option. +* `zabbix_web_conf_mode`: Default: `0644`. The "mode" for the Zabbix configuration file. + +### Zabbix Web specific + +* `zabbix_api_server_url`: This is the url on which the zabbix web interface is available. Default is zabbix.example.com, you should override it. For example, see "Example Playbook" +* `zabbix_url_aliases`: A list with Aliases for the Apache Virtual Host configuration. +* `zabbix_timezone`: Default: `Europe/Amsterdam`. This is the timezone. The Apache Virtual Host needs this parameter. +* `zabbix_vhost`: Default: `true`. When you don't want to create an Apache Virtual Host configuration, you can set it to False. +* `zabbix_web_env`: (Optional) A Dictionary of PHP Environments settings. +* `zabbix_web_conf_web_user`: When provided, the user (which should already exist on the host) will be used for ownership for web/php related processes. (Default set to either `apache` (`www-data` for Debian) or `nginx`). +* `zabbix_web_conf_web_group`: When provided, the group (which should already exist on the host) will be used for ownership for web/php related processes. (Default set to either `apache` (`www-data` for Debian) or `nginx`). +* `zabbix_web_htpasswd`: (Optional) Allow HTTP authentication at the webserver level via a htpasswd file. +* `zabbix_web_htpasswd_file`: Default: `/etc/zabbix/web/htpasswd`. Allows the change the default path to the htpasswd file. +* `zabbix_web_htpasswd_users`: (Optional) Dictionary for creating users via `htpasswd_user` and passphrases via `htpasswd_pass` in htpasswd file. +* `zabbix_web_allowlist_ips`: (Optional) Allow web access at webserver level to a list of defined IPs or CIDR. +* `zabbix_web_connect_ha_backend`: (Optional) Default: `false`. When set to `true` values for Zabbix server will not be written and frontend gets values from database to connect to active cluster node. Set `true` when operating Zabbix servers in a cluste (only >=6.0). +* `zabbix_saml_idp_crt`: (Optional) The path to the certificate of the Identity Provider used for SAML authentication +* `zabbix_saml_sp_crt`: (Optional) The path to the public certificate of Zabbix as Service Provider +* `zabbix_saml_sp_key`: (Optional) The path to the private certificate of Zabbix as Service Provider + +#### Apache configuration + +* `zabbix_apache_vhost_port`: The port on which Zabbix HTTP vhost is running. +* `zabbix_apache_vhost_tls_port`: The port on which Zabbix HTTPS vhost is running. +* `zabbix_apache_vhost_listen_ip`: On which interface the Apache Virtual Host is available. +* `zabbix_apache_can_connect_ldap`: Default: `false`. Set SELinux boolean to allow httpd to connect to LDAP. +* `zabbix_php_install`: Default: `true`. True / False. Switch for extra install of packages for PHP, currently on for Debian/Ubuntu. +* `zabbix_web_max_execution_time`: +* `zabbix_web_memory_limit`: +* `zabbix_web_post_max_size`: +* `zabbix_web_upload_max_filesize`: +* `zabbix_web_max_input_time`: +* `zabbix_apache_include_custom_fragment`: Default: `true`. Includes php_value vars max_execution_time, memory_limit, post_max_size, upload_max_filesize, max_input_time and date.timezone in vhost file.. place those in php-fpm configuration. +* `zabbix_apache_tls`: If the Apache vhost should be configured with TLS encryption or not. +* `zabbix_apache_redirect`: If a redirect should take place from HTTP to HTTPS +* `zabbix_apache_tls_crt`: The path to the TLS certificate file. +* `zabbix_apache_tls_key`: The path to the TLS key file. +* `zabbix_apache_tls_chain`: The path to the TLS certificate chain file. +* `zabbix_apache_SSLPassPhraseDialog`: Type of pass phrase dialog for encrypted private keys. +* `zabbix_apache_SSLSessionCache`: Type of the global/inter-process SSL Session Cache +* `zabbix_apache_SSLSessionCacheTimeout`: Number of seconds before an SSL session expires in the Session Cache +* `zabbix_apache_SSLCryptoDevice`: Enable use of a cryptographic hardware accelerator +* `zabbix_apache_custom_includes`: Configure custom includes. Default: `[]` + +When `zabbix_apache_tls_crt`, `zabbix_apache_tls_key` and/or `zabbix_apache_tls_chain` are used, make sure that these files exists before executing this role. The Zabbix-Web role will not install the mentioned files. + +See https://httpd.apache.org/docs/current/mod/mod_ssl.html for SSL* configuration options for Apache HTTPD. + +#### Nginx configuration + +* `zabbix_nginx_vhost_port`: The port on which Zabbix HTTP vhost is running. +* `zabbix_nginx_vhost_tls_port`: The port on which Zabbix HTTPS vhost is running. +* `zabbix_nginx_tls`: If the Nginx vhost should be configured with TLS encryption or not. +* `zabbix_nginx_tls_crt`: The path to the TLS certificate file. +* `zabbix_nginx_tls_key`: The path to the TLS key file. +* `zabbix_nginx_tls_dhparam`: The path to the TLS DHParam file. +* `zabbix_nginx_tls_session_cache`: Type of the global/inter-process SSL Session Cache +* `zabbix_nginx_tls_session_timeout`: +* `zabbix_nginx_tls_session_tickets`: +* `zabbix_nginx_tls_protocols`: The TLS Protocols to accept. +* `zabbix_nginx_tls_ciphers`: The TLS Ciphers to be allowed. + +When `zabbix_nginx_tls_crt` and `zabbix_nginx_tls_key` are used, make sure that these files exists before executing this role. The Zabbix-Web role will not install the mentioned files. + +#### PHP-FPM + +The following properties are specific to Zabbix 5.0 and for the PHP(-FPM) configuration: + +* `zabbix_php_version`: Either `7.3` or `7.4` (Based on the OS Family). When you want to override the PHP Version. +* `zabbix_php_fpm_session`: The directory where sessions will be stored. If none are provided, defaults are used. +* `zabbix_php_fpm_listen`: The path to a socket file or ipaddress:port combination on which PHP-FPM needs to listen. If none are provided, defaults are used. +* `zabbix_php_fpm_conf_listen`: Default: `true`. If we want to configure the `zabbix_php_fpm_listen` in the PHP-FPM configuration file. +* `zabbix_php_fpm_conf_user`: The owner of the socket file (When `zabbix_php_fpm_listen` contains a patch to a socket file). +* `zabbix_php_fpm_conf_enable_user`: Default: `true`. If we want to configure the owner of the `zabbix_php_fpm_listen` in the PHP-FPM configuration file. +* `zabbix_php_fpm_conf_group`: The group of the owner of the socket file (When `zabbix_php_fpm_listen` contains a patch to a socket file). +* `zabbix_php_fpm_conf_enable_group`: Default: `true`. If we want to configure the group of the `zabbix_php_fpm_listen` in the PHP-FPM configuration file. +* `zabbix_php_fpm_conf_mode`: The mode for the socket file (When `zabbix_php_fpm_listen` contains a patch to a socket file). +* `zabbix_php_fpm_conf_enable_mode`: Default: `true`. If we want to configure the mode of the `zabbix_php_fpm_listen` in the PHP-FPM configuration file. +* `zabbix_php_fpm_dir_etc`: etc HOME root directory of PHP-FPM setup. +* `zabbix_php_fpm_dir_var`: Var HOME root directory of PHP-FPM setup. + +### Zabbix Server + +* `zabbix_server_name`: The name of the Zabbix Server. +* `zabbix_server_database`: The type of database used. Can be: mysql or pgsql +* `zabbix_server_database_long`: The type of database used, but long name. Can be: mysql or postgresql +* `zabbix_server_hostname`: The hostname on which the zabbix-server is running. Default set to: {{ inventory_hostname }} +* `zabbix_server_listenport`: On which port the Zabbix Server is available. Default: 10051 +* `zabbix_server_dbhost`: The hostname on which the database is running. +* `zabbix_server_dbname`: The database name which is used by the Zabbix Server. +* `zabbix_server_dbuser`: The database username which is used by the Zabbix Server. +* `zabbix_server_dbpassword`: The database user password which is used by the Zabbix Server. +* `zabbix_server_dbport`: The database port which is used by the Zabbix Server. + +The following properties are related when using Elasticsearch for history storage: + +* `zabbix_server_history_url`: String with url to the Elasticsearch server or a list if the types are stored on different Elasticsearch URLs. +* `zabbix_server_history_types`: List of history types to store in Elasticsearch. + +See the following links for more information regarding Zabbix and Elasticsearch +https://www.zabbix.com/documentation/3.4/manual/appendix/install/elastic_search_setup +https://www.zabbix.com/documentation/4.0/manual/appendix/install/elastic_search_setup + +## proxy + +When the target host does not have access to the internet, but you do have a proxy available then the following properties needs to be set to download the packages via the proxy: + +* `zabbix_http_proxy` +* `zabbix_https_proxy` + +# Example Playbook + +There are two ways of using the zabbix-web: + +* Single instance +* Multi host setup + +## Single instance + +When there is one host running both Zabbix Server and the Zabbix Web (Running MySQL as database): + +```yaml +- hosts: zabbix-server + become: yes + roles: + - role: geerlingguy.apache + - role: geerlingguy.php + - role: community.zabbix.zabbix_server + zabbix_server_database: mysql + zabbix_server_database_long: mysql + zabbix_server_dbport: 3306 + - role: community.zabbix.zabbix_web + zabbix_api_server_url: zabbix.mydomain.com + zabbix_server_database: mysql + zabbix_server_database_long: mysql + zabbix_server_dbport: 3306 +``` + +## Multi host setup + +This is a two host setup. On one host (Named: "zabbix-server") the Zabbix Server is running, and the other host (Named: zabbix-web) runs Zabbix Web (with MySQL as database): + +```yaml +- hosts: zabbix-server + become: yes + roles: + - role: community.zabbix.zabbix_server + zabbix_server_database: mysql + zabbix_server_database_long: mysql + zabbix_server_dbport: 3306 + +- hosts: zabbix-web + become: yes + roles: + - role: geerlingguy.apache + - role: geerlingguy.php + - role: community.zabbix.zabbix_web + zabbix_api_server_url: zabbix.mydomain.com + zabbix_server_hostname: zabbix-server + zabbix_server_database: mysql + zabbix_server_database_long: mysql + zabbix_server_dbport: 3306 +``` + +## Adding Environment Variables for zabbix_web + +Sometimes you need to add environment variables to your +zabbix.conf.php, for example to add LDAP CA certificates. To do this add a `zabbix_web_env` dictionary: + +```yaml +- hosts: zabbix-web + become: yes + roles: + - role: geerlingguy.apache + - role: geerlingguy.php + php_memory_limit: "128M" + php_max_execution_time: "300" + php_upload_max_filesize: "256M" + php_packages: + - php + - php-fpm + - php-acpu + - role: geerlingguy.apache-php-fpm + - role: community.zabbix.zabbix_web + zabbix_api_server_url: zabbix.mydomain.com + zabbix_server_hostname: zabbix-server + zabbix_server_database: mysql + zabbix_server_database_long: mysql + zabbix_server_dbport: 3306 + zabbix_web_env: + LDAPTLS_CACERT: /etc/ssl/certs/ourcert.pem +``` + +## Using Elasticsearch for history storage + +To use Elasticsearch for history storage you need to configure the `zabbix_server_history_url` and `zabbix_server_history_types`. You will also need to configure Elasticsearch +in the zabbix_server role. + +Zabbix can store the following history types +in Elasticsearch: +* Numeric (unsigned) - `uint` +* Numeric (float) - `dbl` +* Character - `str` +* Log - `log` +* Text - `text` + +To store all history types in the same history URL the following variables should be set (make sure history url points to your Elasticsearch cluster): + +``` +zabbix_server_history_url: "http://localhost:9200" +zabbix_server_history_types: + - 'str' + - 'text' + - 'log' + - 'uint' + - 'dbl' +``` + +# Molecule + +This role is configured to be tested with Molecule. You can find on this page some more information regarding Molecule: + +* http://werner-dijkerman.nl/2016/07/10/testing-ansible-roles-with-molecule-testinfra-and-docker/ +* http://werner-dijkerman.nl/2016/07/27/extending-ansible-role-testing-with-molecule-by-adding-group_vars-dependencies-and-using-travis-ci/ +* http://werner-dijkerman.nl/2016/07/31/testing-ansible-roles-in-a-cluster-setup-with-docker-and-molecule/ + +With each Pull Request, Molecule will be executed via travis.ci. Pull Requests will only be merged once these tests run successfully. + +# License + +GNU General Public License v3.0 or later + +See LICENCE to see the full text. + +# Author Information + +Please send suggestion or pull requests to make this role better. Also let us know if you encounter any issues installing or using this role. + +Github: https://github.com/ansible-collections/community.zabbix |