icinga

Icinga module.

exception spicerack.icinga.IcingaError[source]

Bases: spicerack.exceptions.SpicerackError

Custom exception class for errors of this module.

exception spicerack.icinga.IcingaStatusNotFoundError[source]

Bases: spicerack.icinga.IcingaError

Custom exception class for errors while parsing the Icinga status.

exception spicerack.icinga.IcingaStatusParseError[source]

Bases: spicerack.icinga.IcingaError

Custom exception class for errors while parsing the Icinga status.

class spicerack.icinga.CommandFile(icinga_host: spicerack.remote.RemoteHosts, *, config_file: str = '/etc/icinga/icinga.cfg')[source]

Bases: str

String class to represent an Icinga command file path with cache capabilities.

Get the Icinga host command file where to write the commands and cache it.

Parameters

  • icinga_host (spicerack.remote.RemoteHosts) -- the Icinga host instance.

  • config_file (str, optional) -- the Icinga configuration file to check for the command file directive.

Returns

the Icinga command file path on the Icinga host.

Return type

str

Raises

spicerack.icinga.IcingaError -- if unable to get the command file path.

class spicerack.icinga.HostStatus(*, name: str, state: str, optimal: bool, failed_services: Sequence[Mapping], downtimed: bool, notifications_enabled: bool)[source]

Bases: object

Represent the status of all Icinga checks for a single host.

Initialize the instance.

Parameters

  • name (str) -- the hostname.

  • state (str) -- the Icinga state for the host, one of UP, DOWN, UNREACHABLE``.

  • optimal (bool) -- whether the host is in optimal state (all green).

  • failed_services (list) -- a list of dictionaries representing the failed services.

  • downtimed (bool) -- whether the host is currently downtimed.

  • notifications_enabled -- (bool): whether the host has notifications enabled.

STATE_UP = 'UP'

the Icinga value for a host that is up and running. The other values for the Icinga host state are DOWN and UNREACHABLE.

Type

str

property failed_services: List[str]

Return the list of service names that are failing.

Returns

a list of strings with the check names.

Return type

list

class spicerack.icinga.HostsStatus[source]

Bases: dict

Represent the status of all Icinga checks for a set of hosts.

property failed_hosts: List[str]

Return the list of hostnames that are not up and running. They can either be down or unreachable.

Returns

the list of strings with the hostnames.

Return type

list

property failed_services: Dict[str, List[str]]

Return the list of service names that are failing for each host that has at least one.

Returns

a dict with hostnames as keys and list of failing service name strings as values.

Return type

dict

property non_optimal_hosts: List[str]

Return the list of hostnames that are not in an optimal state.

They can either not being up and running or have at least one failed service.

Returns

a list of strings with the hostnames.

Return type

list

property optimal: bool

Returns True if all the hosts are optimal, False otherwise.

Returns

whether all hosts are optimal.

Return type

bool

class spicerack.icinga.Icinga(icinga_host: spicerack.remote.RemoteHosts)[source]

Bases: object

Class to interact with the Icinga server.

Initialize the instance.

Deprecated since version v0.0.50: use spicerack.icinga.IcingaHosts instead.

Parameters

icinga_host (spicerack.remote.RemoteHosts) -- the RemoteHosts instance for the Icinga server.

downtime_hosts(hosts: spicerack.typing.TypeHosts, reason: spicerack.administrative.Reason, *, duration: datetime.timedelta = datetime.timedelta(seconds=14400)) → None[source]

Downtime hosts on the Icinga server for the given time with a message.

Parameters

  • hosts (spicerack.typing.TypeHosts) -- the set of hostnames or FQDNs to downtime.

  • reason (spicerack.administrative.Reason) -- the reason to set for the downtime on the Icinga server.

  • duration (datetime.timedelta, optional) -- the length of the downtime period.

get_status(hosts: ClusterShell.NodeSet.NodeSet) → spicerack.icinga.HostsStatus[source]

Get the current status of the given hosts from Icinga.

Parameters

hosts (cumin.NodeSet) -- the set of hostnames or FQDNs to iterate the command to.

Returns

the instance that represents the status for the given hosts.

Return type

spicerack.icinga.HostsStatus

Raises
host_command(command: str, hosts: spicerack.typing.TypeHosts, *args: str) → None[source]

Execute a host-specific Icinga command on the Icinga server for a set of hosts.

Parameters

  • command (str) -- the Icinga command to execute.

  • hosts (spicerack.typing.TypeHosts) -- the set of hostnames or FQDNs to iterate the command to.

  • *args (str) -- optional positional arguments to pass to the command.

See also

https://icinga.com/docs/icinga1/latest/en/extcommands2.html

hosts_downtimed(hosts: spicerack.typing.TypeHosts, reason: spicerack.administrative.Reason, *, duration: datetime.timedelta = datetime.timedelta(seconds=14400), remove_on_error: bool = False) → Iterator[None][source]

Context manager to perform actions while the hosts are downtimed on Icinga.

Parameters

  • hosts (spicerack.typing.TypeHosts) -- the set of hostnames or FQDNs to downtime.

  • reason (spicerack.administrative.Reason) -- the reason to set for the downtime on the Icinga server.

  • duration (datetime.timedelta, optional) -- the length of the downtime period.

  • remove_on_error -- should the downtime be removed even if an exception was raised.

Yields

None -- it just yields control to the caller once Icinga has been downtimed and deletes the downtime once getting back the control.

recheck_all_services(hosts: spicerack.typing.TypeHosts) → None[source]

Force recheck of all services associated with a set of hosts.

Parameters

hosts (spicerack.typing.TypeHosts) -- the set of hostnames or FQDNs to recheck.

remove_downtime(hosts: spicerack.typing.TypeHosts) → None[source]

Remove a downtime from a set of hosts.

Parameters

hosts (spicerack.typing.TypeHosts) -- the set of hostnames or FQDNs to remove the downtime from.

wait_for_optimal(hosts: ClusterShell.NodeSet.NodeSet) → None[source]

Waits for an icinga optimal status, else raises an exception.

Parameters

hosts (cumin.NodeSet) -- the set of hostnames or FQDNs to iterate the command to.

Raises

IcingaError --

property command_file: str

Getter for the command_file property.

Returns

the path of the Icinga command file.

Return type

str

Raises

spicerack.icinga.IcingaError -- if unable to get the command file path.

class spicerack.icinga.IcingaHosts(icinga_host: spicerack.remote.RemoteHosts, target_hosts: spicerack.typing.TypeHosts, *, verbatim_hosts: bool = False)[source]

Bases: object

Class to manage the Icinga checks of a given set of hosts.

Initialize the instance.

Parameters

  • icinga_host (spicerack.remote.RemoteHosts) -- the RemoteHosts instance for the Icinga server.

  • target_hosts (spicerack.typing.TypeHosts) -- the target hosts either as a NodeSet instance or a sequence of strings.

  • verbatim_hosts (bool, optional) -- if True use the hosts passed verbatim as is, if instead False, the default, consider the given target hosts as FQDNs and extract their hostnames to be used in Icinga.

downtime(reason: spicerack.administrative.Reason, *, duration: datetime.timedelta = datetime.timedelta(seconds=14400)) → None[source]

Downtime hosts on the Icinga server for the given time with a message.

Parameters
downtimed(reason: spicerack.administrative.Reason, *, duration: datetime.timedelta = datetime.timedelta(seconds=14400), remove_on_error: bool = False) → Iterator[None][source]

Context manager to perform actions while the hosts are downtimed on Icinga.

Parameters

  • reason (spicerack.administrative.Reason) -- the reason to set for the downtime on the Icinga server.

  • duration (datetime.timedelta, optional) -- the length of the downtime period.

  • remove_on_error -- should the downtime be removed even if an exception was raised.

Yields

None -- it just yields control to the caller once Icinga has been downtimed and deletes the downtime once getting back the control.

get_status() → spicerack.icinga.HostsStatus[source]

Get the current status of the given hosts from Icinga.

Returns

the instance that represents the status for the given hosts.

Return type

spicerack.icinga.HostsStatus

Raises
recheck_all_services() → None[source]

Force recheck of all services associated with a set of hosts.

remove_downtime() → None[source]

Remove a downtime from a set of hosts.

run_icinga_command(command: str, *args: str) → None[source]

Execute an Icinga command on the Icinga server for all the current hosts.

This lower level API is meant to be used when the higher level API exposed in this class does not cover a given use case. The arguments passed to the underlying Icinga command will be the hostname plus all the arguments passed to this method. Hence it can be used only with Icinga commands that require a hostname. See the link below for more details on the available Icinga commands and their arguments.

Parameters

  • command (str) -- the Icinga command to execute.

  • *args (str) -- optional positional arguments to pass to the command.

See also

https://icinga.com/docs/icinga1/latest/en/extcommands2.html

wait_for_optimal() → None[source]

Waits for an icinga optimal status, else raises an exception.

Raises

IcingaError -- if the status is not optimal.