zbx

README

[!CAUTION] github.com/ecnepsnai/zbx is deprecated and replaced by git.ecn.io/ian/zbx. All users should migrate to git.ecn.io/ian/zbx for continued updates. Tag v1.0.0 is drop-in compatible copy of the last release of github.com/ecnepsnai/zbx.

zbx

Package zbx is a Zabbix Agent implementation in golang that allows your application to act as a zabbix passive agent and respond to simple requests, or a zabbix active agent and send data to the server.

It is compatible with Zabbix version 4 and newer and supports plain-text and certificate-based TLS.

Usage

Basic Agent

This sets up a basic agent with no encryption.

// This function is called for each incoming request from the Zabbix server
getItem := func(itemKey string) (interface{}, error) {
    if itemKey == "agent.ping" {
        return "1", nil
    } else if itemKey == "runtime.version" {
        return runtime.Version, nil
    }

    // Returning nil, nil means the itemKey was unknown
    return nil, nil
}

// This will block
zbx.Start(getItem, "0.0.0.0:10050")

Agent with TLS

This sets up a certificate-based TLS agent. This package doesn't support PSK-based TLS, as crypto/tls does not support this feature, yet.

// This function is called for each incoming request from the Zabbix server
getItem := func(itemKey string) (interface{}, error) {
    if itemKey == "agent.ping" {
        return "1", nil
    } else if itemKey == "runtime.version" {
        return runtime.Version, nil
    }

    // Returning nil, nil means the itemKey was unknown
    return nil, nil
}

// Load the certificate and key that the zabbix agent will use for incoming connections
// from the Zabbix server
cert, err := tls.LoadX509KeyPair("zabbix.crt", "zabbix.key")
if err != nil {
    panic(err)
}

// This will block
zbx.StartTLS(getItem, "0.0.0.0:10050", cert)

Active Agent

An active agent works by pushing item data directly to the Zabbix server, rather than passive agents where the Zabbix server pulls data from the agent.

The zbx package supports active agents using plain-text and certificate-based TLS. PSK-based TLS is not supported.

session, items, err := zbx.StartActive(
    "myserver.example.com",     // The name of this agent as configured on the zabbix server
    "zabbix.example.com:10051", // The address to the zabbix server's listener - this is different from the web interface
)
if err != nil {
    panic(err)
}

// items contains a slice of what items the zabbix server expects you to send, and how frequently
if len(items) == 0 {
    // If items is empty, then the zabbix server either does not recognize this host (myserver.example.com)
    // or there are no items with the "Zabbix Agent (Active)" type.
    panic("no items")
}

// Active checks work using internal item IDs, which you must map to the item key
// For example, here we'll map the 'agent.ping' item to its id.
var pingItemId int
for _, item := range items {
    if item.Key == "agent.ping" {
        pingItemId = item.ItemId
        break
    }
}
if pingItemId == 0 {
    panic("item not found")
}

// You can send multiple item values at once, but in this example we'll only send one
if err := session.Send(map[int]string{
    pingItemId: "ok",
}); err != nil {
    panic(err)
}

Documentation

Overview

Package zbx is a Zabbix Agent implementation in golang that allows your application to act as a zabbix agent and respond to simple requests.

It is compatible with Zabbix version 4 and newer, however it does not support compression or TLS PSK authentication.

Deprecated: github.com/ecnepsnai/zbx is deprecated and replaced by git.ecn.io/ian/zbx. All users should migrate to git.ecn.io/ian/zbx for continued updates. Tag v1.0.0 is drop-in compatible copy of the last release of github.com/ecnepsnai/zbx.

Example

package main

import (
	"runtime"

	"github.com/ecnepsnai/zbx"
)

func main() {
	// This function is called for each incoming request from the Zabbix server
	getItem := func(itemKey string) (interface{}, error) {
		if itemKey == "agent.ping" {
			return "1", nil
		} else if itemKey == "runtime.version" {
			return runtime.Version, nil
		}

		// Returning nil, nil means the itemKey was unknown
		return nil, nil
	}

	// This will block
	zbx.Start(getItem, "0.0.0.0:10050")
}

Index

• Variables
• func Start(itemFunc ItemFunc, address string) error
• func StartActive(agentHostname, serverAddress string) (*ActiveSession, []SupportedItem, error)
• func StartActiveTls(agentHostname, serverAddress string, certificate tls.Certificate) (*ActiveSession, []SupportedItem, error)
• func StartListener(itemFunc ItemFunc, l net.Listener)
• func StartTLS(itemFunc ItemFunc, address string, certificate tls.Certificate) error
• type ActiveSession
  • func (s *ActiveSession) Send(values map[int]string) error
• type ItemFunc
• type SupportedItem

Examples

• Package
• Start
• StartActive
• StartTLS

Variables

var ErrorLog io.Writer = os.Stderr

ErrorLog is the writer that error messages are written to. By default this is stderr.

Functions

func Start

func Start(itemFunc ItemFunc, address string) error

Start the Zabbix agent on the specified address. Will block and always return on error. Will panic if itemFunc is nil.

Example

package main

import (
	"runtime"

	"github.com/ecnepsnai/zbx"
)

func main() {
	// This function is called for each incoming request from the Zabbix server
	getItem := func(itemKey string) (interface{}, error) {
		if itemKey == "agent.ping" {
			return "1", nil
		} else if itemKey == "runtime.version" {
			return runtime.Version, nil
		}

		// Returning nil, nil means the itemKey was unknown
		return nil, nil
	}

	// This will block
	zbx.Start(getItem, "0.0.0.0:10050")
}

func StartActive

func StartActive(agentHostname, serverAddress string) (*ActiveSession, []SupportedItem, error)

StartActive will prepare a connection for Zabbix active agent checks. With active agent checks, the agent (that is, the software that is importing and using this zbx package) is responsible for sending data to the zabbix server, rather than the server asking the agent.

When you start an active session, you must identify yourself to the agent using the agentHostname parameter. The server will produce a list of items that it expects you to send, and the intervals it expects them to be sent at.

For enhanced security, it's recommended that TLS authentication is used, see StartActiveTls for details.

Example

package main

import (
	"github.com/ecnepsnai/zbx"
)

func main() {
	session, items, err := zbx.StartActive(
		"myserver.example.com",     // The name of this agent as configured on the zabbix server
		"zabbix.example.com:10051", // The address to the zabbix server's listener - this is different from the web interface
	)
	if err != nil {
		panic(err)
	}

	// items contains a slice of what items the zabbix server expects you to send, and how frequently
	if len(items) == 0 {
		// If items is empty, then the zabbix server either does not recognize this host (myserver.example.com)
		// or there are no items with the "Zabbix Agent (Active)" type.
		panic("no items")
	}

	// Active checks work using internal item IDs, which you must map to the item key
	// For example, here we'll map the 'agent.ping' item to its id.
	var pingItemId int
	for _, item := range items {
		if item.Key == "agent.ping" {
			pingItemId = item.ItemId
			break
		}
	}
	if pingItemId == 0 {
		panic("item not found")
	}

	// You can send multiple item values at once, but in this example we'll only send one
	if err := session.Send(map[int]string{
		pingItemId: "ok",
	}); err != nil {
		panic(err)
	}
}

func StartActiveTls

func StartActiveTls(agentHostname, serverAddress string, certificate tls.Certificate) (*ActiveSession, []SupportedItem, error)

StartActiveTls wraps an active connection using TLS authentication. See StartActive for more details.

func StartListener

func StartListener(itemFunc ItemFunc, l net.Listener)

Start the Zabbix agent on the specified listener.

func StartTLS

func StartTLS(itemFunc ItemFunc, address string, certificate tls.Certificate) error

StartTLS will start the Zabbix agent on the specified address with TLS. The agent will present the given certificate to the server when connected. Will panic if itemFunc is nil.

Example

package main

import (
	"crypto/tls"
	"runtime"

	"github.com/ecnepsnai/zbx"
)

func main() {
	// This function is called for each incoming request from the Zabbix server
	getItem := func(itemKey string) (interface{}, error) {
		if itemKey == "agent.ping" {
			return "1", nil
		} else if itemKey == "runtime.version" {
			return runtime.Version, nil
		}

		// Returning nil, nil means the itemKey was unknown
		return nil, nil
	}

	// Load the certificate and key that the zabbix agent will use for incoming connections
	// from the Zabbix server
	cert, err := tls.LoadX509KeyPair("zabbix.crt", "zabbix.key")
	if err != nil {
		panic(err)
	}

	// This will block
	zbx.StartTLS(getItem, "0.0.0.0:10050", cert)
}

Types

type ActiveSession

type ActiveSession struct {
	// contains filtered or unexported fields
}

Describes a session for a zabbix active check

func (*ActiveSession) Send

func (s *ActiveSession) Send(values map[int]string) error

Send will send the mapping of itemId to value to the zabbix server. Items should match those presented by the zabbix server when this session was started. Each call to ActiveSession.Send will make a new connection to the Zabbix server, so you may wish to batch item values together.

type ItemFunc

type ItemFunc func(key string) (interface{}, error)

ItemFunc describes the method invoked when the Zabbix Server (or proxy) is requesting an item from this agent. The returned interface be encoded as a string and returned to the server.

If error is not nil, it will be sent back to the server. If (nil, nil) is returned then it is assumed the key is unknown.

Any calls to `panic()` will be recovered from and written to ErrorLog and the server will act as if the key was unknown.

type SupportedItem

type SupportedItem struct {
	Key     string `json:"key"`
	ItemId  int    `json:"itemid"`
	Delay   string `json:"delay"`
	Timeout string `json:"timeout"`
}

Describes a supported item for zabbix active checks