README

这是一个用 PHP 编写的简单 Icinga2 API 客户端。目前它只具有读取功能。将来它还将能够写入 Icinga2。

安装

要使用此客户端，只需将其添加到您的包要求中，使用 composer

composer require rzuw/icinga2

客户端配置

以下设置应设置为使此客户端工作。

$config = array
(
    "host" => ""
    "port" => ""
    // should be set when you decide for username and password login
    "user" => ""
    "password" => ""
    // should be used when you decide for certificate login
    "cert" => ""
    "key" => ""
);

Icinga2 后端配置

完整的 Icinga2 后端 API 设置配置可在 Icinga2 文档中找到。将提供 API 配置的示例，一个用于基于用户名和密码的认证，另一个使用 X509 证书。

配置 API

要配置 API 设置，您需要创建主证书

icinga2 pki new-ca
cd /var/lib/icinga2/certs/
icinga2 pki new-cert --cn your-master-instance-fqdn --csr your-master-instance-fqdn.csr --key your-master-instance-fqdn.key
icinga2 pki sign-csr --csr your-master-instance-fqdn.csr --cert your-master-instance-fqdn.crt

将 ca.crt 复制到您的客户端，您将需要它在未来的认证中。

然后，在 /etc/icinga2/features-available/api.conf 中添加以下 API 配置

/**
 * The API listener is used for distributed monitoring setups.
 */
object ApiListener "api" {
 accept_commands = true
 accept_config = true
 ticket_salt = TicketSalt
}

通过命令行启用 API 设置或创建链接

# Using Commandline
icinga2 feature eanble api
# Or Using link
ln -s /etc/icinga2/features-available/api.conf /etc/icinga2/features-enabled/api.conf

使用用户名和密码

在 /etc/icinga2/conf.d/api-users.conf 中添加您的用户，并使用给定的设置

object ApiUser "your-user"{
  password = "your-password"
  permissions = ["*"]
}

要测试设置，请使用 curl

curl -u your-user:your-password --cacert ca.crt 'https://your-icinga2-domain:5665/v1'

使用 X509 证书

可以使用证书使用 Icinga2 API，为此，您需要创建所需的 CA 证书、客户端证书，然后使用 CA 签名证书。完整的文档可在 Icinga2 网站上找到。

cd /var/lib/icinga2/certs/
icinga2 pki new-cert --cn your-client-cn --csr your-client-cn.csr --key your-client-cn.key
icinga2 pki sign-csr --csr your-client-cn.csr --cert your-client-cn.crt

在 /etc/icinga2/conf.d/api-users.conf 中添加您的用户，并使用给定的设置

object ApiUser "your-client-user"{
  client_cn = "your-client-cn"
  permissions = ["*"]
}

重启 Icinga2 守护进程

systemctl restart icinga2

将 your-client-cn.crt 和 your-client-cn.key 复制到您的 API 客户端，它们可以使用了。

要测试客户端，请简单地使用以下 curl 命令

curl --cert your-client-cn.crt --key your-client-cn.key --cacert ca.crt 'https://your-icinga-api-domain:5665/v1'
# On Successful attempt you will see:
# <html><head><title>Icinga 2</title></head><h1>Hello from Icinga 2 (Version: r2.8.0-1)!</h1><p>You are authenticated as <b>your-client-user</b>. Your user has the following permissions:</p> <ul><li>*</li></ul><p>More information about API requests is available in the <a href="https://docs.icinga.com/icinga2/latest" target="_blank">documentation</a>.</p></html>

用法

要使用此客户端，只需创建 Icinga2Api 类的实例并在其中加载配置。

$config = array
(
    "host" => ""
    "port" => ""
    // should be set when you decide for username and password login
    "user" => ""
    "password" => ""
    // should be used when you decide for certificate login
    "cert" => ""
    "key" => ""
);
$icinga2 = new Icinga2($config);
$matchedHosts = $icinga2->getHosts(array("match(\"" . $this->hostData["hostname"] . "*\",host.name)"

查看测试用例以获取更多示例。

测试

要测试此客户端，您需要安装 phpunit。并且应该设置以下环境变量。

export ICINGA2HOST="Your API HOST"
export ICINGA2PORT="YOUR API PORT"
export ICINGA2USERNAME= ""
export ICINGA2PASSWORD=""
export ICINGA2CERTPATH=""
export ICINGA2KEYPATH=""
export ICINGA2CAPATH=""
export ICINGA2KEYPASSWORD=""

rzuw / icinga2

维护者

详细信息