1# community.zabbix.zabbix_proxy role 2 3![Zabbix Proxy](https://github.com/ansible-collections/community.zabbix/workflows/community.zabbix.zabbix_proxy/badge.svg) 4 5**Table of Contents** 6 7- [Overview](#overview) 8 * [Operating systems](#operating-systems) 9 * [Zabbix Versions](#zabbix-versions) 10- [Role Variables](#role-variables) 11 * [Main variables](#main-variables) 12 + [Overall Zabbix](#overall-zabbix) 13 + [SElinux](#selinux) 14 + [Zabbix Proxy](#zabbix-proxy) 15 + [Database specific](#database-specific) 16 + [TLS Specific configuration](#tls-specific-configuration) 17 * [proxy](#proxy) 18 * [Database](#database) 19 + [MySQL](#mysql) 20 - [Local Setup](#local-setup) 21 - [Separate Setup](#separate-setup) 22 + [PostgreSQL](#postgresql) 23 - [Local Setup](#local-setup-1) 24 - [Separate Setup](#separate-setup-1) 25 + [SQLite3](#sqlite3) 26 * [Zabbix API variables](#zabbix-api-variables) 27- [Example Playbook](#example-playbook) 28- [Molecule](#molecule) 29- [License](#license) 30- [Author Information](#author-information) 31 32# Overview 33 34## Operating systems 35 36This role will work on the following operating systems: 37 38 * Red Hat 39 * Debian 40 * Ubuntu 41 42So, you'll need one of those operating systems.. :-) 43Please send Pull Requests or suggestions when you want to use this role for other Operating systems. 44 45## Zabbix Versions 46 47See the following list of supported Operating systems with the Zabbix releases. 48 49| Zabbix | 5.2 | 5.0 | 4.4 | 4.0 (LTS) | 3.0 (LTS) | 50|---------------------|-----|-----|-----|-----------|-----------| 51| Red Hat Fam 8 | V | V | V | | | 52| Red Hat Fam 7 | V | V | V | V | V | 53| Red Hat Fam 6 | V | V | | | V | 54| Red Hat Fam 5 | V | V | | | V | 55| Fedora | | | V | V | | 56| Ubuntu 20.04 focal | V | V | | | | 57| Ubuntu 19.10 eoan | | | | | | 58| Ubuntu 18.04 bionic | V | V | V | V | | 59| Ubuntu 16.04 xenial | V | V | V | V | | 60| Ubuntu 14.04 trusty | V | V | V | V | V | 61| Debian 10 buster | V | V | V | | | 62| Debian 9 stretch | V | V | V | V | | 63| Debian 8 jessie | V | V | V | V | V | 64| Debian 7 wheezy | | | | V | V | 65| macOS 10.15 | | | V | V | | 66| macOS 10.14 | | | V | V | | 67 68# Role Variables 69 70## Main variables 71 72The following is an overview of all available configuration default for this role. 73 74### Overall Zabbix 75 76* `zabbix_proxy_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. 77* `zabbix_repo`: Default: `zabbix` 78 * `epel`: install agent from EPEL repo 79 * `zabbix`: (default) install agent from Zabbix repo 80 * `other`: install agent from pre-existing or other repo 81* `zabbix_repo_yum`: A list with Yum repository configuration. 82* `zabbix_repo_yum_schema`: Default: `https`. Option to change the web schema for the yum repository(http/https) 83* `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 `*`. 84* `zabbix_repo_yum_enabled`: A list with repository names that should be enabled when installing Zabbix component specific packages. 85 86### SElinux 87 88* `zabbix_selinux`: Default: `False`. Enables an SELinux policy so that the Proxy will run. 89 90### Zabbix Proxy 91 92* `zabbix_proxy_ip`: The IP address of the host. When not provided, it will be determined via the `ansible_default_ipv4` fact. 93* `zabbix_server_host`: The ip or dns name for the zabbix-server machine. 94* `zabbix_server_port`: The port on which the zabbix-server is running. Default: 10051 95* `*zabbix_proxy_package_state`: Default: `present`. Can be overridden to `latest` to update packages 96* `zabbix_proxy_install_database_client`: Default: `True`. False does not install database client. 97* `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. 98* `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. 99* `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. 100* `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. 101* `zabbix_proxy_username`: Default: `zabbix`. The name of the account on the host. Will only be used when `zabbix_repo: epel` is used. 102* `zabbix_proxy_userid`: The UID of the account on the host. Will only be used when `zabbix_repo: epel` is used. 103* `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. 104* `zabbix_proxy_groupid`: The GID of the group on the host. Will only be used when `zabbix_repo: epel` is used. 105* `zabbix_proxy_include_mode`: Default: `0755`. The "mode" for the directory configured with `zabbix_proxy_include`. 106* `zabbix_proxy_conf_mode`: Default: `0644`. The "mode" for the Zabbix configuration file. 107* `zabbix_proxy_statsallowedip`: Default: `127.0.0.1`. Allowed IP foe remote gathering of the ZabbixPorixy internal metrics. 108 109### Database specific 110 111* `zabbix_proxy_dbhost_run_install`: Default: `True`. When set to `True`, sql files will be executed on the host running the database. 112* `zabbix_proxy_database`: Default: `pgsql`. The type of database used. Can be: `mysql`, `pgsql` or `sqlite3` 113* `zabbix_proxy_database_long`: Default: `postgresql`. The type of database used, but long name. Can be: `mysql`, `postgresql` or `sqlite3` 114* `zabbix_proxy_dbhost`: The hostname on which the database is running. Will be ignored when `sqlite3` is used as database. 115* `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. 116* `zabbix_proxy_dbname`: The database name which is used by the Zabbix Proxy. 117* `zabbix_proxy_dbuser`: The database username which is used by the Zabbix Proxy. Will be ignored when `sqlite3` is used as database. 118* `zabbix_proxy_dbpassword`: The database user password which is used by the Zabbix Proxy. Will be ignored when `sqlite3` is used as database. 119* `zabbix_proxy_dbport`: The database port which is used by the Zabbix Proxy. Will be ignored when `sqlite3` is used as database. 120* `zabbix_database_creation`: Default: `True`. When you don't want to create the database including user, you can set it to False. 121* `zabbix_proxy_install_database_client`: Default: `True`. False does not install database client. Default true 122* `zabbix_database_sqlload`:True / False. When you don't want to load the sql files into the database, you can set it to False. 123* `zabbix_proxy_dbencoding`: Default: `utf8`. The encoding for the MySQL database. 124* `zabbix_proxy_dbcollation`: Default: `utf8_bin`. The collation for the MySQL database.zabbix_proxy_ 125 126### TLS Specific configuration 127 128These variables are specific for Zabbix 3.0 and higher: 129 130* `zabbix_proxy_tlsconnect`: How the agent should connect to server or proxy. Used for active checks. 131 Possible values: 132 * unencrypted 133 * psk 134 * cert 135* `zabbix_proxy_tlsaccept`: What incoming connections to accept. 136 Possible values: 137 * unencrypted 138 * psk 139 * cert 140* `zabbix_proxy_tlscafile`: Full pathname of a file containing the top-level CA(s) certificates for peer certificate verification. 141* `zabbix_proxy_tlscrlfile`: Full pathname of a file containing revoked certificates. 142* `zabbix_proxy_tlsservercertissuer`: Allowed server certificate issuer. 143* `zabbix_proxy_tlsservercertsubject`: Allowed server certificate subject. 144* `zabbix_proxy_tlscertfile`: Full pathname of a file containing the agent certificate or certificate chain. 145* `zabbix_proxy_tlskeyfile`: Full pathname of a file containing the agent private key. 146* `zabbix_proxy_dbtlsconnect`: Setting this option enforces to use TLS connection to database: 147 148`required` - connect using TLS 149`verify_ca` - connect using TLS and verify certificate 150`verify_full` - connect using TLS, verify certificate and verify that database identity specified by DBHost matches its certificate 151 152On `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. 153By default not set to any option and the behaviour depends on database configuration. 154This parameter is supported since Zabbix 5.0.0. 155 156* `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. 157* `zabbix_proxy_dbtlscertfile`: Full pathname of file containing Zabbix Proxy certificate for authenticating to database. This parameter is supported since Zabbix 5.0.0. 158* `zabbix_proxy_dbtlskeyfile`: Full pathname of file containing the private key for authenticating to database. This parameter is supported since Zabbix 5.0.0. 159* `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. 160* `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. 161 162## proxy 163 164When 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: 165 166* `zabbix_http_proxy` 167* `zabbix_https_proxy` 168 169## Database 170 171With Zabbix Proxy you can make use of 2 different databases: 172 173* `mysql` 174* `postgresql` 175* `SQLite3` 176 177In the following paragraphs we dive into both setups. 178 179### MySQL 180 181To make the Zabbix Proxy work with a `MySQL` database, there are 2 types on setup: 182 1831. Local setup, `MySQL` running on same host as the Zabbix Proxy; 1842. Separate setup, `MySQL` running on a different host than the Zabbix Proxy. 185 186#### Local Setup 187 188We need to have the following dependencies met: 189 1901. 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. 1912. 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: 192 193```yaml 194zabbix_proxy_database: mysql 195zabbix_proxy_database_long: mysql 196zabbix_proxy_dbport: 3306 197zabbix_proxy_dbpassword: <SOME_SECRET_STRING> 198``` 199 200Please 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`. 2013. 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. 202 203#### Separate Setup 204 205We need to have the following dependencies met: 206 2071. 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. 2082. 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: 209 210```yaml 211zabbix_proxy_database: mysql 212zabbix_proxy_database_long: mysql 213zabbix_proxy_dbport: 3306 214zabbix_proxy_dbhost: mysql-host 215zabbix_proxy_dbhost_run_install: false 216zabbix_proxy_dbpassword: <SOME_SECRET_STRING> 217zabbix_proxy_privileged_host: '%' 218zabbix_proxy_mysql_login_host: mysql-host 219zabbix_proxy_mysql_login_user: root 220zabbix_proxy_mysql_login_password: changeme 221zabbix_proxy_mysql_login_port: 3306 222``` 223 224Please 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`. 225 226The `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. 227 2283. 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. 229 230### PostgreSQL 231 232To make the Zabbix Proxy work with a `PgSQL` database, there are 2 types on setup: 233 2341. Local setup, `PgSQL` running on same host as the Zabbix Proxy; 2352. Separate setup, `PgSQL` running on a different host than the Zabbix Proxy. 236 237#### Local Setup 238 239We need to have the following dependencies met: 240 2411. 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. 2422. 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: 243 244```yaml 245zabbix_proxy_database: pgsql 246zabbix_proxy_database_long: postgresql 247zabbix_proxy_dbport: 5432 248zabbix_proxy_dbpassword: <SOME_SECRET_STRING> 249``` 250 251Please 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`. 2523. 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. 253 254#### Separate Setup 255 256We need to have the following dependencies met: 257 2581. 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. 2592. 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: 260 261```yaml 262zabbix_proxy_database: pgsql 263zabbix_proxy_database_long: postgresql 264zabbix_proxy_dbport: 5432 265zabbix_proxy_dbhost: pgsql-host 266zabbix_proxy_dbhost_run_install: false 267zabbix_proxy_dbpassword: <SOME_SECRET_STRING> 268zabbix_proxy_privileged_host: '%' 269zabbix_proxy_pgsql_login_host: pgsql-host 270zabbix_proxy_pgsql_login_user: postgres 271zabbix_proxy_pgsql_login_password: changeme 272zabbix_proxy_pgsql_login_port: 5432 273``` 274 275Please 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`. 276 277The `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. 278 2793. 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_ 280 281### SQLite3 282 283The 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. 284 285The following properties needs to be set when using `SQLite3` as the database: 286 287```yaml 288zabbix_proxy_database: sqlite3 289zabbix_proxy_database_long: sqlite3 290zabbix_proxy_dbname: /path/to/sqlite3.db 291``` 292 293NOTE: 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` 294 295## Zabbix API variables 296 297These 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. 298 299When `zabbix_api_create_proxy` is set to `True`, it will install on the host executing the Ansible playbook the `zabbix-api` python module. 300 301* `zabbix_url`: The url on which the Zabbix webpage is available. Example: http://zabbix.example.com 302* `zabbix_api_http_user`: The http user to access zabbix url with Basic Auth 303* `zabbix_api_http_password`: The http password to access zabbix url with Basic Auth 304* `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_create_proxy`. Default: `False` 305* `zabbix_api_user`: Username of user which has API access. 306* `zabbix_api_pass`: Password for the user which has API access. 307* `zabbix_create_proxy`: 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`. 308* `zabbix_proxy_status`: active (Default) if the proxy needs to be active or passive. 309 310# Example Playbook 311 312Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too: 313 314```yaml 315 - hosts: zabbix-proxy 316 roles: 317 - role: community.zabbix.zabbix_proxy 318 zabbix_server_host: 192.168.1.1 319 zabbix_proxy_database: mysql 320 zabbix_proxy_database_long: mysql 321``` 322 323# Molecule 324 325This role is configured to be tested with Molecule. You can find on this page some more information regarding Molecule: 326 327* http://werner-dijkerman.nl/2016/07/10/testing-ansible-roles-with-molecule-testinfra-and-docker/ 328* http://werner-dijkerman.nl/2016/07/27/extending-ansible-role-testing-with-molecule-by-adding-group_vars-dependencies-and-using-travis-ci/ 329* http://werner-dijkerman.nl/2016/07/31/testing-ansible-roles-in-a-cluster-setup-with-docker-and-molecule/ 330 331With each Pull Request, Molecule will be executed via travis.ci. Pull Requests will only be merged once these tests run successfully. 332 333# License 334 335GNU General Public License v3.0 or later 336 337See LICENCE to see the full text. 338 339# Author Information 340 341Please send suggestion or pull requests to make this role better. Also let us know if you encounter any issues installing or using this role. 342 343Github: https://github.com/ansible-collections/community.zabbix 344