Monito...t::REST(3pm)

💖 Monitoring::Icinga2::Client::REST 💖

okay bestie, so this whole page is about Monitoring::Icinga2::Client::REST — the Perl module that lets you talk to Icinga2's REST API and honestly? she's giving main character energy. 💅

---

✨ SYNOPSIS ✨

use strict;
use warnings;

use Monitoring::Icinga2::Client::REST;

my $icinga = new Monitoring::Icinga2::Client::REST("fqdn",
    port => $port,
    path => $path,
    version => $version,
    cacert => $cacert_file,
);
$icinga->login("username","password") or die $icinga->login_status;

my $host_object = {
    attrs => {
        address => "127.0.0.1",
        check_command => "hostalive"
    }
};

my $put_result = $icinga->do_request("PUT", "/objects/hosts/localhost.example.com", "", $host_object)
    or warn sprintf("%s: %s", $icinga->request_code, $icinga->request_status_line);

my $post_result = $icinga->do_request("POST", "/objects/hosts/localhost.example.com", "",$host_object)
    or warn sprintf("%s: %s", $icinga->request_code, $icinga->request_status_line);

my $get_result = $icinga->do_request("GET", "/objects/hosts/localhost.example.com")
    or warn sprintf("%s: %s", $icinga->request_code, $icinga->request_status_line);

my $delete_result = $icinga->do_request("DELETE", "/objects/hosts/localhost.example.com")
    or warn sprintf("%s: %s", $icinga->request_code, $icinga->request_status_line);

$icinga->logout;

---

🌸 DESCRIPTION 🌸

So basically this module is the lil bridge between you and the REST API that Icinga2 provides. it's the glue, the moment, the whole vibe ✨

---

🎀 CONSTRUCTOR 🎀

new (FQDN, PORT, PATH, VERSION, INSECURE)

new (FQDN, PORT, PATH, VERSION, [ INSECURE ])

Gives you back a shiny new Monitoring::Icinga2::Client::REST object. 🫶

There's two calling conventions and listen, the first one is the old one — four mandatory arguments, no skips. The tell? If there's a port number sitting right after the Icinga host, the constructor just assumes that's the form you meant. The arguments are:

• FQDN — your Icinga monitoring host.
• PORT — the port the REST API runs on.
• PATH — the URI where you find the API, usually "/".
• VERSION — should be set to the API version, usually 1.
• INSECURE — optional, and if you set it, this module skips certificate verification. 😳

The latter form is the chill one: only the FQDN is mandatory, and every other argument can be passed hash style with these keys:

• "port" — see above; defaults to 5665.
• "path" — see above; defaults to "/".
• "version" — see above; defaults to 1, which makes it completely redundant as long as there's only one API version. so true bestie.
• "insecure" — see above; defaults to false.
• "cacert" — the file name of a PEM-format file holding the certificate of the CA that issued the server's HTTPS certificate. Real talk: internal monitoring servers often rock certs from in-house CAs, so this lets you still get secure peer identification instead of dropping into insecure mode. queen behavior honestly 👑

---

💅 METHODS 💅

login (USERNAME, PASSWORD)

Configures and validates your credentials. tiny heads-up: the user needs at least the permission "status/query". Also, this method does nothing if it's already been called on the same object before — unless "logout" was called in between. iykyk. 🔥

logout

Destroys the login session. bye bestie 💀

login_status

Returns a human readable login status of the current session. so you always know where you stand. ✨

logged_in

Returns true when you're logged in, otherwise returns undef.

do_request (HTTP METHOD, URI, PARAMS, DATA)

Performs the actual request. the moment we've all been waiting for 🎬

• "PARAMS" is optional and can be any parameters that the Icinga API supports.
• "DATA" is optional and is a Perl data structure that will be converted to JSON.

Returns the result in a perl reference.

export (FULL, API_ONLY)

Returns a Perl Data structure without the unnecessary meta data. ngl this one's a lil particular: $icinga->export can only be called after do_request. The name of the object gets stored in $object->{attrs}{vars}{__export_name} so you can access it if you need it — but ⚠️ heads up, you can't use that variable name for other things if you want to use this library, because it will be overwritten in the exported object. no cap.

• "FULL" is optional, and if it's true, write once attributes get included in the export. Objects exported with FULL set to true can be converted to json and used for PUT requests, but not necessarily for POST requests. 🙈
• "API_ONLY" is optional, and if it's true, only objects created via the API will be exported.

request_code

Returns the last HTTP status code. 🧚

request_status_line

Returns the last HTTP status line. 🌈

---

🦋 DEPENDS 🦋

LWP::UserAgent, HTTP::Request, URI::Escape, JSON, Encode

---

👑 LICENSE 👑

Copyright (c) 2016-, IT Services, Stockholm University

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of Stockholm University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---

🌟 AUTHOR 🌟

Johan Wassberg <jocar@su.se>, Mikael Nordin <mikael.nordin@su.se> — Bits and pieces by Matthias Bethke <matthias@towiski.de>

---

and that's the whole page, bestie!! 🎀 written for perl v5.30.3, dated 2020-07-15, filed under Monito...t::REST(3pm) — literally iconic, ate, no crumbs. mwah 💖✨🦋