Skip to content

Latest commit

 

History

History
445 lines (346 loc) · 23.2 KB

ZABBIX_SERVER_ROLE.md

File metadata and controls

445 lines (346 loc) · 23.2 KB
Raw

community.zabbix.zabbix_server role

Zabbix Server

Table of Contents

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:

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:

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:

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
Red Hat Fam 9 V V V
Red Hat Fam 8 V V V
Ubuntu 24.04 noble V V
Ubuntu 22.04 jammy V V V
Ubuntu 20.04 focal V V V
Ubuntu 18.04 bionic V
Debian 12 bookworm V V
Debian 11 bullseye V V V
Debian 10 buster V

You can bypass this matrix by setting enable_version_check: false

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: 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_server_version: 6.0.
  • zabbix_server_version_minor: When you want to specify a minor version to be installed. RedHat only. Default set to: * (latest available)
  • 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_server_disable_repo: A list of repos to disable during install. Default epel.
  • zabbix_service_state: Default: started. Can be overridden to stopped if needed
  • zabbix_service_enabled: Default: True Can be overridden to False if needed
  • zabbix_repo_deb_url: The URL to the Zabbix repository. Default http://repo.zabbix.com/zabbix/{{ zabbix_server_version }}/{{ ansible_distribution.lower() }}
  • zabbix_repo_deb_component: The repository component for Debian installs. Default main.
  • zabbix_repo_deb_gpg_key_url: The URL to download the Zabbix GPG key from. Default http://repo.zabbix.com/zabbix-official-repo.key.
  • zabbix_repo_deb_include_deb_src: True, if deb-src should be included in the zabbix.sources entry. Default true.

SElinux

  • zabbix_server_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_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_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.

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_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_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_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_server_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_server_database_sqlload:True / False. When you don't want to load the sql files into the database, you can set it to False.
  • zabbix_server_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.

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:

   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:
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:
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.

  1. 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:
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:
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.

  1. 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.

Configuration Variables

The following table lists all variables that are exposed to modify the configuration of the zabbix_server.conf file. Specific details of each variable can be found in the Zabbix documentation.

NOTE: Only variables with a default value appear in the defaults file, all others must be added.

Zabbix Name Variable Name Default Value Notes
AlertScriptsPath zabbix_server_alertscriptspath /usr/lib/zabbix/alertscripts
AllowRoot zabbix_server_allowroot 0
AllowUnsupportedDBVersions zabbix_server_allowunsupporteddbversions 0
CacheSize zabbix_server_cachesize
CacheUpdateFrequency zabbix_server_cacheupdatefrequency
DBHost zabbix_server_dbhost localhost
DBName zabbix_server_dbname zabbix-server
DBPassword zabbix_server_dbpassword zabbix-server
DBPort zabbix_server_dbport 5432
DBSchema zabbix_server_dbschema
DBSocket zabbix_server_dbsocket
DBTLSCAFile zabbix_server_dbtlscafile
DBTLSCertFile zabbix_server_dbtlscertfile
DBTLSCipher zabbix_server_dbtlscipher
DBTLSCipher13 zabbix_server_dbtlscipher13
DBTLSConnect zabbix_server_dbtlsconnect
DBTLSKeyFile zabbix_server_dbtlskeyfile
DBUser zabbix_server_dbuser zabbix-server
DebugLevel zabbix_server_debuglevel 3
ExportDir zabbix_server_exportdir
ExportFileSize zabbix_server_exportfilesize 1G
ExportType zabbix_server_exporttype
ExternalScripts zabbix_server_externalscriptspath /usr/lib/zabbix/externalscripts
Fping6Location zabbix_server_fping6location OS Specific Value
FpingLocation zabbix_server_fpinglocation OS Specific Value
HANodeName zabbix_server_hanodename
HistoryCacheSize zabbix_server_historycachesize
HistoryIndexCacheSize zabbix_server_historyindexcachesize
HistoryStorageDateIndex zabbix_server_historystoragedateindex 0
HistoryStorageTypes zabbix_server_historystoragetypes uint,dbl,str,log,text
HistoryStorageURL zabbix_server_historystorageurl
HousekeepingFrequency zabbix_server_housekeepingfrequency 1
Include zabbix_server_include /etc/zabbix/zabbix_server.conf.d
JavaGateway zabbix_server_javagateway
JavaGatewayPort zabbix_server_javagatewayport 10052
ListenBacklog zabbix_server_listenbacklog
ListenIP zabbix_server_listenip
ListenPort zabbix_server_listenport 10051
LoadModule zabbix_server_loadmodule
LoadModulePath zabbix_server_loadmodulepath ${libdir}/modules
LogFile zabbix_server_logfile /var/log/zabbix/zabbix_server.log
LogFileSize zabbix_server_logfilesize 10
LogSlowQueries zabbix_server_logslowqueries 0
LogType zabbix_server_logtype file
MaxHousekeeperDelete zabbix_server_maxhousekeeperdelete 500
NodeAddress zabbix_server_nodeaddress
PidFile zabbix_server_pidfile /var/run/zabbix/zabbix_server.pid
ProxyConfigFrequency zabbix_server_proxyconfigfrequency
ProxyDataFrequency zabbix_server_proxydatafrequency 1
SNMPTrapperFile zabbix_server_snmptrapperfile
SocketDir zabbix_server_socketdir /var/run/zabbix
SourceIP zabbix_server_sourceip
SSHKeyLocation zabbix_server_sshkeylocation
SSLCALocation zabbix_server_sslcalocation
SSLCertLocation zabbix_server_sslcertlocation ${datadir}/zabbix/ssl/certs
SSLKeyLocation zabbix_server_sslkeylocation ${datadir}/zabbix/ssl/keys
StartAlerters zabbix_server_startalerters
StartConnectors zabbix_server_connectors Version 6.4 or later
StartDBSyncers zabbix_server_startdbsyncers 4
StartDiscoverers zabbix_server_startdiscoverers 1
StartEscalators zabbix_server_startescalators 1
StartHistoryPollers zabbix_server_starthistorypollers
StartHTTPPollers zabbix_server_starthttppollers 1
StartIPMIPollers zabbix_server_startipmipollers 0
StartJavaPollers zabbix_server_startjavapollers 0
StartLLDProcessors zabbix_server_startlldprocessors
StartODBCPollers zabbix_server_startodbcpollers
StartPingers zabbix_server_startpingers 1
StartPollers zabbix_server_startpollers 5
StartPollersUnreachable zabbix_server_startpollersunreachable 1
StartPreprocessors zabbix_server_startpreprocessors
StartProxyPollers zabbix_server_startproxypollers
StartReportWriters zabbix_server_startreportwriters 0
StartSNMPTrapper zabbix_server_startsnmptrapper 0
StartTimers zabbix_server_starttimers 1
StartTrappers zabbix_server_starttrappers 5
StartVMwareCollectors zabbix_server_startvmwarecollectors 0
StasAllowedIP zabbix_server_statsallowedip
Timeout zabbix_server_timeout 3
TLSCAFile zabbix_server_tlscafile
TLSCertFile zabbix_server_tlscertfile
TLSCipherAll zabbix_server_tlscipherall
TLSCipherAll13 zabbix_server_tlscipherall13
TLSCipherCert zabbix_server_tlsciphercert
TLSCipherCert13 zabbix_server_tlsciphercert13
TLSCipherPSK zabbix_server_tlscipherpsk
TLSCipherPSK13 zabbix_server_tlscipherpsk13
TLSCRLFile zabbix_server_tlscrlfile
TLSKeyFile zabbix_server_tlskeyfile
TmpDir zabbix_server_tmpdir /tmp
TrapperTimeout zabbix_server_trappertimeout 300
TrendCacheSize zabbix_server_trendcachesize
TrendFunctionCacheSize zabbix_server_trendfunctioncachesize
UnavailableDelay zabbix_server_unavailabledelay 60
UnreachableDelay zabbix_server_unreachabledelay 15
UnreachablePeriod zabbix_server_unreachableperiod 45
User zabbix_server_user zabbix
ValueCacheSize zabbix_server_valuecachesize
Vault zabbix_server_vault Version 6.2 or later
VaultDBPath zabbix_server_vaultdbpath
VaultTLSKeyFile zabbix_server_vaulttlskeyfile Version 6.2 or later
VaultTLSCertFile zabbix_server_vaulttlscertfile Version 6.2 or later
VaultToken zabbix_server_vaulttoken
VaultURL zabbix_server_vaulturl https://127.0.0.1:8200
VMwareCacheSize zabbix_server_vmwarecachesize
VMwareFrequency zabbix_server_vmwarefrequency 60
VMwarePerfFrequency zabbix_server_vmwareperffrequency 60
VMwareTimeout zabbix_server_vmwaretimeout 10
WebServiceURL zabbix_server_webserviceurl

Tags

The majority of tasks within this role are tagged as follows:

  • install: Tasks associated with the installation of software.
  • dependencies: Installation tasks related to dependencies that aren't part of the core zabbix installation.
  • database: Tasks associated with the installation or configuration of the database.
  • api: Tasks associated with using the Zabbix API to connect and modify the Zabbix server.
  • config: Tasks associated with the configuration of Zabbix or a supporting service.
  • service: Tasks associated with managing a service.

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:

  - 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:

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