Connect Zabbix (Local Connector)

A collector installed on one of your Windows servers reads the Zabbix frontend's API over HTTPS once a day and sends the result to HARVEN. HARVEN never connects to Zabbix, and the collector never changes its configuration.

For the general flow of adding a source, see Connect Data Sources.

Prerequisites

• Zabbix 6.0 LTS, 7.0 LTS or 8.0 LTS

• A Windows server (PowerShell 5.1 or later) that reaches the Zabbix frontend over HTTPS, and harven.ai on port 443

• A Zabbix Super admin to create the collector's role, user and API token

• Administrator rights on that server for the install

Setup

Step 1 — Prepare Zabbix and the server

In Zabbix

Once, as a Super admin, in the Users menu:

1. User roles: create a role, for example HARVEN collector, with User type Super admin.

2. Access to UI elements: Zabbix refuses a role with no UI element at all, so leave only Dashboards ticked (Monitoring → Dashboard on 6.0), untick every other element, and untick Default access to new UI elements. Leave Access to services and Access to modules as they are: they only cover screens and methods this account cannot use.

3. API access: Enabled. API methods: Allow list, with exactly these methods: host.get, hostinterface.get, hostgroup.get, problem.get, event.get, user.get, usergroup.get, role.get, token.get, proxy.get, maintenance.get, action.get, authentication.get, settings.get, auditlog.get

4. Access to actions: untick every action except Manage API tokens, and untick Default access to new actions. From 7.0, Invoke "Execute now" on read-only hosts stays ticked and greyed out: it has no effect here, leave it. Manage API tokens lets the collector list API tokens; it cannot create or change one, as the allow list holds no write method.

5. Users: create a user, for example harven-collector, with that role, in the built-in group No access to the frontend. The account can then never open the frontend.

6. API tokens: create a token for that user with an expiry date. 12 months is recommended: HARVEN shows the expiry, so it can be renewed in time. The token is shown once; copy it for step 4, where it goes on the server. It never reaches HARVEN.

The collector only reads: every request is one of these methods, apart from a first apiinfo.version call, which Zabbix answers without a token and which reveals only its version. The role's allow list refuses anything else at Zabbix's own end.

⚠️ Without Super admin: a role of type Admin works, with the same allow list minus authentication.get, auditlog.get and action.get, and a user group of its own with Read permission on the host groups to cover. Only those groups are read; actions, users, user groups, roles and API tokens stay empty, the last four with a warning on every run.

Network

Install on a Windows server that reaches the Zabbix frontend. Not on a domain controller.

Outbound HTTPS 443 to api.harven.ai, dbapi.harven.ai and auth.harven.ai.

Outbound HTTPS to the Zabbix frontend, at the address you open in a browser, often ending in /zabbix. A plain http:// frontend is refused: the API token is a Super admin credential.

No inbound rule is needed.

Behind a proxy, pass -ProxyUrl or set HTTPS_PROXY machine-wide. The proxy is used for HARVEN only, never for Zabbix.

Frontend certificate

A Zabbix frontend often presents a self-signed certificate. That is normal; trust it in one of two ways:

• Pin it: the installer's -TrustSourceCertificate reads the certificate during the install, prints its SHA-256 fingerprint and asks you to compare it before pinning it (certificate_sha256). Compare it with the one the frontend's web server shows.

• Or set ca_file to the PEM of your own certificate authority, if it issued the frontend's certificate.

To read the fingerprint beforehand, run on the collector's server:

$frontend = '<ZABBIX-FRONTEND-HOST>'
$port = 443
$client = [Net.Sockets.TcpClient]::new($frontend, $port)
$stream = [Net.Security.SslStream]::new($client.GetStream(), $false, { $true })
$stream.AuthenticateAsClient($frontend)
([BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash(
    $stream.RemoteCertificate.GetRawCertData())) -replace '-').ToLower()
$stream.Dispose(); $client.Dispose()

Step 2 — Download and verify the archive

Download the archive from this page, on the server itself: the link expires within minutes.

Get-FileHash — checks the archive's SHA-256 against the one shown here.

Get-AuthenticodeSignature — checks the signature of the binary and the scripts.

Step 3 — Get the enrolment code

1. Save this data source

2. Click Generate a code

3. Copy it: it is shown once, works once and expires after 24 hours

Step 4 — Install

Run the installer. It installs the collector, enrols it, stores the API token, then checks that it can read Zabbix.

.\install.ps1 -Source zabbix `
    -SourceOptions '{"address":"<ZABBIX-FRONTEND-URL>"}' `
    -TrustSourceCertificate -SourceUsername '<ZABBIX-SERVICE-USER>'

It prompts for the enrolment code, then for a password: paste the API token there.

To store a new token after renewing it, run this and paste the new token at the password prompt:

& "$env:ProgramData\Harven\Collector\harven-collector.exe" source-credentials `
    -connector zabbix -username '<ZABBIX-SERVICE-USER>' -grant-read 'NT AUTHORITY\LOCAL SERVICE'

If the final check fails, the install stops with an error. Fix the cause and run the same command again.

Step 5 — Check the first collection

Start the task by hand: Task Scheduler → \Harven\, or Start-ScheduledTask.

The run then appears in this page's history.

Settings on the collector's server

Collected data

• zabbix_hosts — Monitored hosts: whether each is enabled and its agent answering, how its agent traffic is encrypted, its maintenance state, groups, templates and inventory.

• zabbix_host_interfaces — Agent, SNMP, IPMI and JMX interfaces with their address, availability and, for SNMP, version and security level.

• zabbix_problems — Operational problems (disk, service, availability) open now or raised in the last 30 days, with severity, acknowledgement and resolution. Not security detections.

• zabbix_users — Zabbix accounts: role, whether enabled, MFA, last login and failed logins.

• zabbix_user_groups — Frontend access, MFA, debug mode and host-group permissions of each user group.

• zabbix_roles — User type, API access, and whether a role may run scripts on monitored hosts.

• zabbix_api_tokens — Each API token's owner, expiry and last use.

• zabbix_actions — Actions: what triggers each one, whether it runs scripts or adds hosts on its own, and who it notifies.

• zabbix_proxies — Mode, state, version and encryption of each proxy.

• zabbix_maintenances — Maintenance windows, their hosts, and whether they stop data collection.

• zabbix_server — The server itself: version, authentication and password policy, MFA, and the expiry of the collector's token.

Never collected

The collector reads the tables above and nothing else. It never collects:

• Any configuration change: it only reads

• The metrics Zabbix gathers from your hosts: item values, history and trends

• Passwords, API token values, encryption keys, or the IPMI and LDAP passwords Zabbix stores

• Problem comments, or the entries of Zabbix's audit log: it is read only to date each user's last login, and only that date is sent

The audit log on your server records counts and outcomes, never data or credentials.

Operation

• Files: %ProgramData%\Harven\Collector (configuration, credentials, logs).

• Scheduled task: \Harven\ in Task Scheduler, one per connector. Disable it to stop collecting.

• Store a renewed API token: harven-collector source-credentials -connector <name> -username <account>.

• Windows Event Log, source Harven Local Connector: 1000 started, 1001 committed, 1002 committed with warnings, 1003 failed, 1010 enrolled.

After a restore or a reinstall

Stored credentials are bound to the machine and do not survive a restore or a clone. Generate a new code on this page, run the installer again, then source-credentials.

Troubleshooting

The task history shows an exit code:

Uninstall

• uninstall.ps1 -Connector <name> removes the task, its profile and its credentials. -All removes everything; -KeepLogs keeps the audit log.

• In Zabbix, delete the API token, the harven-collector user and its role, and with a role of type Admin, its user group.

• Delete this data source in HARVEN, or disable its collector.

Official documentation

• Zabbix API documentation

• Zabbix user roles

Need help? Contact [email protected].