Submodules

pretiac (`init.py`)

pretiac is a Python module to interact with the Icinga 2 RESTful API.

Set and configure the default client.

Parameters:

config_file – The path of the configuration file to load.
api_endpoint_host – The domain or the IP address of the API endpoint, e. g. icinga.example.com, localhost or 127.0.0.1.
api_endpoint_port – The TCP port of the API endpoint, for example 5665.
http_basic_username – The name of the API user used in the HTTP basic authentification, e. g. apiuser.
http_basic_password – The password of the API user used in the HTTP basic authentification, e. g. password.
client_private_key – The file path of the client’s private RSA key, for example /etc/pretiac/api-client.key.pem.
client_certificate – The file path of the client’s certificate, for example /etc/pretiac/api-client.cert.pem.
ca_certificate – The file path of the Icinga CA (Certification Authority), for example /var/lib/icinga2/certs/ca.crt.
suppress_exception – If set to True, no exceptions are thrown.

pretiac.get_default_client() → Client[source]

Get the default client.

This function intentionally has no input parameters. Use the function set_default_client() to set a new configured client.

However, this function loads a client configured by configuration files in the following order (if the function set_default_client() was not called before):

The file path in the environment variable PRETIAC_CONFIG_FILE.
The configuration file in the home folder ~/.pretiac.yml.
The configuration file at /etc/pretiac/config.yml.

---
api_endpoint_host: localhost
api_endpoint_port: 5665
client_private_key: /etc/pretiac/api-client.key.pem
client_certificate: /etc/pretiac/api-client.cert.pem
ca_certificate: /etc/pretiac/ca.crt
new_host_defaults:
    templates: [passive-host]
new_service_defaults:
    templates: [passive-service]
    attrs:
        check_interval: monthly

pretiac.client

A high level client with typed return values.

class pretiac.client.CheckResponse(*, code: int, status: str)[source]

Bases: BaseModel

code: int

status: str

model_config: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pretiac.client.CheckError(*, error: int, status: str)[source]

Bases: BaseModel

error: int

status: str

model_config: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Bases: object

The high level client with typed output.

It is a wrapper around the RawClient.

raw_client: RawClient

property api_endpoint_host: str | None

property api_endpoint_port: int | None

property http_basic_username: str | None

property http_basic_password: str | None

property client_certificate: str | None

property client_private_key: str | None

property ca_certificate: str | None

get_api_user(name: str) → ApiUser[source]

get_api_users() → Sequence[ApiUser][source]

get_check_commands() → Sequence[CheckCommand][source]

get_dependencys() → Sequence[Dependency][source]

get_endpoints() → Sequence[Endpoint][source]

Create a new host. If no host configuration is specified, the template generic-host is assigned.

Parameters:

name – The name of the host.
display_name – A short description of the host.
templates – Import existing configuration templates for this object type. Note: These templates must either be statically configured or provided in config packages.
attrs – Set specific object attributes for this object type.
object_config – Bundle of all configurations required to create a host.
suppress_exception – If this parameter is set to True, no exceptions are thrown.

The method call

client.create_host(name='framework')

creates for example a configuration file in the location /var/lib/icinga2/api/packages/_api/33d433c5-2c2f-4159-84fc-41395ddcd04d/conf.d/hosts/framework.conf with the content:

object Host "framework" {
    import "generic-host"

    version = 1725393956.244954
    zone = "master"
}

get_host(name: str) → Host | None[source]

Get a single host.

Parameters:: name – The name of the host.

get_hosts() → Sequence[Host][source]: Get all hosts.

delete_host(name: str) → None[source]

Delete a single host.

Parameters:: name – The name of the host.

Create a new service. If no service configuration is specified, the dummy check command is assigned.

Parameters:

name – The name of the service.
host – The name of the host.
display_name – A short description of the service.
templates – Import existing configuration templates for this object type. Note: These templates must either be statically configured or provided in config packages.
attrs – Set specific object attributes for this object type.
object_config – Bundle of all configurations required to create a service.
suppress_exception – If this parameter is set to True, no exceptions are thrown.

client.create_service(name='procs_zombie', host='framework', display_name='Zombie processes')

Creates a configuration file like /var/lib/icinga2/api/packages/_api/33d433c5-2c2f-4159-84fc-41395ddcd04d/conf.d/services/framework!procs_zombie.conf this one:

object Service "procs_zombie" {
    check_command = "dummy"
    display_name = "Zombie processes"
    host_name = "framework"
    version = 1725393956.973319
    zone = "master"
}

get_service(name: str | None = None, host: str | None = None, service: str | None = None) → Service[source]

Parameters:

name – The full name of the service, for example host!service.
host – The name of the host.
service – The name of the service.

get_services() → Sequence[Service][source]

delete_service(name: str | None = None, host: str | None = None, service: str | None = None) → None[source]

Parameters:

name – The full name of the service, for example host!service.
host – The name of the host.
service – The name of the service.

Send a check result for a service and create the host or the service if necessary.

Parameters:

service – The name of the service.
host – The name of the host.
exit_status – For services: 0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN, for hosts: 0=UP, 1=DOWN.
plugin_output – One or more lines of the plugin main output. Does not contain the performance data.
performance_data – The performance data.
check_command – The first entry should be the check commands path, then one entry for each command line option followed by an entry for each of its argument. Alternativly a single string can be used.
check_source – Usually the name of the command_endpoint.
execution_start – The timestamp where a script/process started its execution.
execution_end – The timestamp where a script/process ended its execution. This timestamp is used in features to determine e.g. the metric timestamp.
ttl – Time-to-live duration in seconds for this check result. The next expected check result is now + ttl where freshness checks are executed.
create – Whether non-existent services and hosts should be created.
display_name – A short description of the service, if it needs to be created.
new_host_defaults – If a new host needs to be created, use this defaults.
new_service_defaults – If a new service needs to be created, use this defaults.

get_time_periods() → Sequence[TimePeriod][source]

get_users() → Sequence[User][source]

get_user_groups() → Sequence[UserGroup][source]

get_zones() → Sequence[Zone][source]

subscribe_events(types: Sequence[Literal['CheckResult', 'StateChange', 'Notification', 'AcknowledgementSet', 'AcknowledgementCleared', 'CommentAdded', 'CommentRemoved', 'DowntimeAdded', 'DowntimeRemoved', 'DowntimeStarted', 'DowntimeTriggered', 'ObjectCreated', 'ObjectDeleted', 'ObjectModified']], queue: str, filter: str | None = None, filter_vars: dict[str, Any] | None = None)[source]

get_status() → Sequence[StatusMessage][source]

list_config_packages() → Sequence[ConfigPackage][source]

list_config_stage_files(package_name: str, stage_name: str) → ConfigPackageStageFiles[source]

Parameters:

package_name – Package names with the _ prefix are reserved for internal packages and must not be used. You can recognize _api, _etc and _cluster when querying specific objects and packages.
stage_name – The stage name, for example 7e7861c8-8008-4e8d-9910-2a0bb26921bd.

list_all_config_stage_files() → list[ConfigPackageStageFiles][source]

delete_config(package_name: str, stage_name: str | None)[source]

Delete a configuration package or a configuration stage entirely.

If the parameter stage_name is not specified, the entire configuration package is deleted. If the parameter stage_name is provided, only the specified configuration stage is deleted.

Parameters:

package_name – Package names with the _ prefix are reserved for internal packages and must not be used. You can recognize _api, _etc and _cluster when querying specific objects and packages.
stage_name – The stage name, for example 7e7861c8-8008-4e8d-9910-2a0bb26921bd.

get_types() → list[TypeInfo][source]

get_variables() → list[Variable][source]

pretiac.config

class pretiac.config.ObjectConfig(templates: Sequence[str] | None = None, attrs: Payload | None = None)[source]

Bases: object

Bundles all configuration required to create an object.

templates: Sequence[str] | None: Import existing configuration templates for this object type. Note: These templates must either be statically configured or provided in config packages.

attrs: dict[str, Any] | None: Set specific object attributes for this object type.

Bases: object

See:: pretiac (JS)

config_file: Path | None: The path of the loaded configuration file.

api_endpoint_host: str | None: The domain or the IP address of the API endpoint, e. g. icinga.example.com, localhost or 127.0.0.1.

api_endpoint_port: int | None

The TCP port of the API endpoint, for example 5665.

See:: Icinca Object Types (apilistener)

http_basic_username: str | None

The name of the API user used in the HTTP basic authentification, e. g. apiuser.

object ApiUser "apiuser" {
    ...
}

See:: Icinca Object Types (apiuser)

http_basic_password: str | None

The password of the API user used in the HTTP basic authentification, e. g. password.

object ApiUser "apiuser" {
    password = "password"
}

See:: Icinca Object Types

client_private_key: str | None

The file path of the client’s private RSA key, for example /etc/pretiac/api-client.key.pem.

The RSA private key is created with this command:

icinga2 pki new-cert \
    --cn api-client \
    --key api-client.key.pem \
    --csr api-client.csr.pem

client_certificate: str | None

The file path of the client certificate.

The certificate is created with this command:

icinga2 pki sign-csr \
    --csr api-client.csr.pem \
    --cert api-client.cert.pem

ca_certificate: str | None

The file path of the Icinga CA (Certification Authority).

The CA certificate is located at /var/lib/icinga2/certs/ca.crt. This command copies the certificate to the local host.

scp icinga-master:/var/lib/icinga2/certs/ca.crt .

suppress_exception: bool | None: If set to True, no exceptions are thrown.

new_host_defaults: ObjectConfig | None: If a new host needs to be created, use this defaults.

new_service_defaults: ObjectConfig | None: If a new service needs to be created, use this defaults.

check() → None[source]: Check if all required values are set.

pretiac.config.load_config_file(config_file: str | Path | None = None) → Config[source]

Load the configuration file in YAML format.

The file path of the loaded configuration file is determined in this order:

The parameter config_file of this function.
The file path in the environment variable PRETIAC_CONFIG_FILE.
The configuration file in the home folder ~/.pretiac.yml.
The configuration file at /etc/pretiac/config.yml.

Parameters:: config_file – The path of the configuration file to load.

Parameters:

config – A configuration object that has already been populated.
config_file – The path of the configuration file to load. If this value is set to false no configuration file will be loaded.
api_endpoint_host – The domain or the IP address of the API endpoint, e. g. icinga.example.com, localhost or 127.0.0.1.
api_endpoint_port – The TCP port of the API endpoint, for example 5665.
http_basic_username – The name of the API user used in the HTTP basic authentification, e. g. apiuser.
http_basic_password – The password of the API user used in the HTTP basic authentification, e. g. password.
client_private_key – The file path of the client’s private RSA key, for example /etc/pretiac/api-client.key.pem.
client_certificate – The file path of the client’s certificate, for example /etc/pretiac/api-client.cert.pem.
ca_certificate – The file path of the Icinga CA (Certification Authority), for example /var/lib/icinga2/certs/ca.crt.
suppress_exception – If set to True, no exceptions are thrown.
new_host_defaults – If a new host needs to be created, use this defaults.
new_service_defaults – If a new service needs to be created, use this defaults.

pretiac.exceptions

Icinga 2 API client exceptions

exception pretiac.exceptions.PretiacException[source]

Bases: Exception

Icinga 2 API exception class

exception pretiac.exceptions.PretiacRequestException(message: str, response: Payload)[source]

Bases: PretiacException

Icinga 2 API Request exception class

response: Payload

exception pretiac.exceptions.PretiacConfigFileException[source]

Bases: Exception

Icinga 2 API config file exception class

pretiac.object_types

All available config object types.

Listed in the same order as in this Markdown document.

pretiac.object_types.OptionalStr

An empty string is set to None by the Pydantic validator.

alias of Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]

pretiac.object_types.MonitoringObjectName

see doc/09-object-types.md object-types-monitoring

alias of Literal[‘ApiUser’, ‘CheckCommand’, ‘Dependency’, ‘Endpoint’, ‘EventCommand’, ‘Host’, ‘HostGroup’, ‘Notification’, ‘NotificationCommand’, ‘ScheduledDowntime’, ‘Service’, ‘ServiceGroup’, ‘TimePeriod’, ‘User’, ‘UserGroup’, ‘Zone’]

pretiac.object_types.RuntimeObjectName

see [doc/09-object-types.md runtime-objects-](https://github.com/Icinga/icinga2/b

alias of Literal[‘Comment’, ‘Downtime’]

pretiac.object_types.FeatureObjectName

see doc/09-object-types.md features-

alias of Literal[‘ApiListener’, ‘CheckerComponent’, ‘CompatLogger’, ‘ElasticsearchWriter’, ‘ExternalCommandListener’, ‘FileLogger’, ‘GelfWriter’, ‘GraphiteWriter’, ‘IcingaApplication’, ‘IcingaDB’, ‘IdoMySqlConnection’, ‘IdoPgsqlConnection’, ‘InfluxdbWriter’, ‘Influxdb2Writer’, ‘JournaldLogger’, ‘LiveStatusListener’, ‘NotificationComponent’, ‘OpenTsdbWriter’, ‘PerfdataWriter’, ‘SyslogLogger’, ‘WindowsEventLogLogger’]

pretiac.object_types.get_object_types_names() → list[str][source]

pretiac.object_types.normalize_to_plural_snake_object_type_name(object_type_name: str) → str[source]

for example: ApiUser to api_users

Returns:: A pluralized object type name in the snake case.

pretiac.object_types.pluralize_to_lower_object_type_name(object_type_name: Literal['ApiUser', 'CheckCommand', 'Dependency', 'Endpoint', 'EventCommand', 'Host', 'HostGroup', 'Notification', 'NotificationCommand', 'ScheduledDowntime', 'Service', 'ServiceGroup', 'TimePeriod', 'User', 'UserGroup', 'Zone', 'Comment', 'Downtime', 'ApiListener', 'CheckerComponent', 'CompatLogger', 'ElasticsearchWriter', 'ExternalCommandListener', 'FileLogger', 'GelfWriter', 'GraphiteWriter', 'IcingaApplication', 'IcingaDB', 'IdoMySqlConnection', 'IdoPgsqlConnection', 'InfluxdbWriter', 'Influxdb2Writer', 'JournaldLogger', 'LiveStatusListener', 'NotificationComponent', 'OpenTsdbWriter', 'PerfdataWriter', 'SyslogLogger', 'WindowsEventLogLogger']) → str[source]: for example: ApiUser to apiusers

pretiac.object_types.RequestMethod

https://github.com/psf/requests/blob/a3ce6f007597f14029e6b6f54676c34196aa050e/src/requests/api.py#L17

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods

alias of Literal[‘GET’, ‘OPTIONS’, ‘HEAD’, ‘POST’, ‘PUT’, ‘PATCH’, ‘DELETE’]

class pretiac.object_types.SourceLocation(path: str, first_line: int, first_column: int, last_line: int, last_column: int)[source]

Bases: object

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/remote/templatequeryhandler.cpp#L29-L35

path: str: /etc/icinga2-custom/conf.d/api-users.conf

first_line: int

first_column: int

last_line: int

last_column: int

class pretiac.object_types.HAMode(*values)[source]

Bases: Enum

HA = High-Availability

See:: lib/base/configobject.ti L12-L16

HARunOnce

HARunEverywhere

class pretiac.object_types.StateType(*values)[source]

Bases: Enum

see: lib/icinga/checkresult.ti L38-L43

StateTypeSoft

StateTypeHard

class pretiac.object_types.Dictionary[source]: Bases: object

pretiac.object_types.Timestamp

for example 1699475880.364077

See:: lib/base/value.hpp L15

pretiac.object_types.Value

A type that can hold an arbitrary value.

lib/base/value.hpp L31-L145

class pretiac.object_types.ServiceState(*values)[source]

Bases: Enum

0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN

https://github.com/Icinga/icinga2/blob/a8adfeda60232260e3eee6d68fa5f4787bb6a245/lib/icinga/checkresult.ti#L22-L33

OK

WARNING

CRITICAL

UNKNOWN

class pretiac.object_types.HostState(*values)[source]

Bases: Enum

0=UP, 1=DOWN.

https://github.com/Icinga/icinga2/blob/a8adfeda60232260e3eee6d68fa5f4787bb6a245/lib/icinga/checkresult.ti#L11-L20

UP

DOWN

pretiac.object_types.get_service_state(state: HostState | ServiceState | Literal[0, 1, 2, 3] | int | Any) → ServiceState[source]

class pretiac.object_types.CheckResult(exit_status: int, output: str, performance_data: list[str] | None, check_source: str, scheduling_source: str, state: ServiceState, previous_hard_state: ServiceState | int, command: list[str] | str | None, execution_start: float, execution_end: float, schedule_start: float, schedule_end: float, active: bool, vars_before: dict[str, Any] | None, vars_after: dict[str, Any], ttl: int)[source]

Bases: object

The attributes are as listed in the offical Icinga2 documentation.

See:: doc/08-advanced-topics/#checkresult
See:: lib/icinga/checkresult.ti

type

exit_status: int

The exit status returned by the check execution.

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L55

output: str

The check output.

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L59

performance_data: list[str] | None

Array of performance data values.

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L60

check_source: str: Name of the node executing the check.

scheduling_source: str: Name of the node scheduling the check.

state: ServiceState

The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L57

previous_hard_state: ServiceState | int

Sometimes 99?

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L58C1-L58C49

command: list[str] | str | None

Array of command with shell-escaped arguments or command line string.

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L54

execution_start: float

Check execution start time (as a UNIX timestamp).

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L51

execution_end: float

Check execution end time (as a UNIX timestamp).

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L52

schedule_start: float

Scheduled check execution start time (as a UNIX timestamp).

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L49

schedule_end: float

Scheduled check execution end time (as a UNIX timestamp).

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L50

active: bool

Whether the result is from an active or passive check.

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L62-L64

vars_before: dict[str, Any] | None

Internal attribute used for calculations.

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L70

vars_after: dict[str, Any]: Internal attribute used for calculations.

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L71

ttl: int

Time-to-live duration in seconds for this check result. The next expected check result is now + ttl where freshness checks are executed.

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/checkresult.ti#L68

class pretiac.object_types.ConfigObject(name: str | None = None, type: str | None = None, zone: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, package: str | None = None, templates: Sequence[str] | None = None, source_location: SourceLocation | None = None, active: bool | None = None, paused: bool | None = None, ha_mode: HAMode | None = None, original_attributes: dict[str, Any] | None = None, version: float | None = None)[source]

Bases: object

See:: lib/base/configobject.ti L57-L92

name: str | None

See:: lib/base/configobject.ti L59-L68

type: str | None

zone: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]

See:: lib/base/configobject.ti L69

package: str | None

for example _etc

See:: lib/base/configobject.ti L70

templates: Sequence[str] | None

See:: lib/base/configobject.ti L71

source_location: SourceLocation | None

See:: lib/base/configobject.ti L72-L74

active: bool | None

See:: lib/base/configobject.ti L75

paused: bool | None

See:: lib/base/configobject.ti L76-L78

ha_mode: HAMode | None

See:: lib/base/configobject.ti L83

original_attributes: dict[str, Any] | None

See:: lib/base/configobject.ti L87

version: float | None

See:: lib/base/configobject.ti L88-L90

Bases: ConfigObject

See:: lib/icinga/customvarobject.ti L10

vars: dict[str, Any] | None

See:: lib/icinga/customvarobject.ti L12

class pretiac.object_types.Checkable(name: str | None = None, type: str | None = None, zone: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, package: str | None = None, templates: Sequence[str] | None = None, source_location: SourceLocation | None = None, active: bool | None = None, paused: bool | None = None, ha_mode: HAMode | None = None, original_attributes: dict[str, Any] | None = None, version: float | None = None, vars: dict[str, Any] | None = None, check_command: str | None = None, max_check_attempts: int | None = None, check_period: str | None = None, check_timeout: int | float | str | bool | Any | None = None, check_interval: float | None = None, retry_interval: float | None = None, event_command: str | None = None, volatile: bool | None = None, enable_active_checks: bool | None = None, enable_passive_checks: bool | None = None, enable_event_handler: bool | None = None, enable_notifications: bool | None = None, enable_flapping: bool | None = None, enable_perfdata: bool | None = None, flapping_ignore_states: Sequence[str] | None = None, flapping_threshold: float | None = None, flapping_threshold_low: float | None = None, flapping_threshold_high: float | None = None, notes: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, notes_url: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, action_url: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, icon_image: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, icon_image_alt: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, next_check: float | None = None, check_attempt: int | None = None, state_type: StateType | None = None, last_state_type: StateType | None = None, last_reachable: bool | None = None, last_check_result: CheckResult | None = None, last_state_change: float | None = None, last_hard_state_change: float | None = None, last_state_unreachable: float | None = None, previous_state_change: float | None = None, severity: int | None = None, problem: bool | None = None, handled: bool | None = None, next_update: float | None = None, force_next_check: bool | None = None, acknowledgement: int | None = None, acknowledgement_expiry: float | None = None, acknowledgement_last_change: float | None = None, force_next_notification: bool | None = None, last_check: float | None = None, downtime_depth: int | None = None, flapping_current: float | None = None, flapping_last_change: float | None = None, flapping: bool | None = None, command_endpoint: str | None = None, executions: Dictionary | None = None)[source]

Bases: CustomVarObject

See:: lib/icinga/checkable.ti

check_command: str | None

The name of the check command.

See:: doc/09-object-types.md L717

max_check_attempts: int | None

The float of times a service is re-checked before changing into a hard state. Defaults to 3.

See:: doc/09-object-types.md L718

check_period: str | None

The name of a time period which determines when this service should be checked. Not set by default (effectively 24x7).

See:: doc/09-object-types.md L719

Check command timeout in seconds. Overrides the CheckCommand’s timeout attribute.

See:: doc/09-object-types.md L720

check_interval: float | None

The check interval (in seconds). This interval is used for checks when the service is in a HARD state. Defaults to 5m.

See:: doc/09-object-types.md L721

retry_interval: float | None: This interval is used for checks when the service is in a SOFT state. Defaults to 1m. Note: This does not affect the scheduling after a passive check result.

event_command: str | None

volatile: bool | None

enable_active_checks: bool | None

enable_passive_checks: bool | None

enable_event_handler: bool | None

enable_notifications: bool | None

enable_flapping: bool | None

enable_perfdata: bool | None

flapping_ignore_states: Sequence[str] | None

flapping_threshold: float | None: deprecated

flapping_threshold_low: float | None

flapping_threshold_high: float | None

notes: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]: Optional. Notes for the checkable.

notes_url: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]: Optional. URL for notes for the checkable (for example, in notification commands).

action_url: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]: Optional. URL for actions for the checkable (for example, an external graphing tool).

icon_image: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]: Optional. Icon image for the checkable. Used by external interfaces only.

icon_image_alt: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]: Optional. Icon image description for the checkable. Used by external interface only.

next_check: float | None

check_attempt: int | None

state_type: StateType | None

last_state_type: StateType | None

last_reachable: bool | None

last_check_result: CheckResult | None

last_state_change: float | None

last_hard_state_change: float | None

last_state_unreachable: float | None

previous_state_change: float | None

severity: int | None

problem: bool | None

handled: bool | None

next_update: float | None

force_next_check: bool | None

acknowledgement: int | None

acknowledgement_expiry: float | None

acknowledgement_last_change: float | None

force_next_notification: bool | None

last_check: float | None

downtime_depth: int | None

flapping_current: float | None

flapping_last_change: float | None

flapping: bool | None

command_endpoint: str | None

executions: Dictionary | None

Bases: ConfigObject

ApiUser objects are used for authentication against the Icinga 2 API.

object ApiUser "root" {
    password = "mysecretapipassword"
    permissions = [ "*" ]
}

Tags: Object type, Monitoring object type

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#apiuser :see: lib/remote/apiuser.ti :see: doc/09-object-types.md L41-L63

password: str | None

Password string. Note: This attribute is hidden in API responses.

See:: lib/remote/apiuser.ti L14

client_cn: str | None

Client Common Name (CN).

Tags: config

See:: lib/remote/apiuser.ti L16

permissions: Sequence[str] | None

Array of permissions. Either as string or dictionary with the keys permission and filter. The latter must be specified as function.

Tags: config

See:: lib/remote/apiuser.ti L17
See:: lib/remote/apiuser.ti L21-L28

class pretiac.object_types.Function(type: str, name: str, side_effect_free: bool, deprecated: bool, arguments: Sequence[str])[source]

Bases: object

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/base/function.ti#L10-L16

type: str

name: str

side_effect_free: bool

deprecated: bool

arguments: Sequence[str]

Bases: object

Command arguments can be defined as key-value-pairs in the arguments dictionary. Best practice is to assign a dictionary as value which provides additional details such as the description next to the value.

Example

arguments = {
    "--parameter" = {
        description = "..."
        value = "..."
    }
}

Tags: Object type, Monitoring object type

See:: doc/09-object-types.md L117-L150
See:: lib/icinga/command.ti L30-L46
See:: lib/icinga/command.ti L33-L45

key: str | None

value: str | Function | Any | None

description: str | None

required: bool | None

skip_key: bool | None

repeat_key: bool | None

set_if: str | Function | None

order: float | None

separator: str | None

Bases: CustomVarObject

A check command definition. Additional default command custom variables can be defined here.

Example

object CheckCommand "http" {
    command = [ PluginDir + "/check_http" ]

    arguments = {
        "-H" = "$http_vhost$"
        "-I" = "$http_address$"
        "-u" = "$http_uri$"
        "-p" = "$http_port$"
        "-S" = {
            set_if = "$http_ssl$"
        }
        "--sni" = {
            set_if = "$http_sni$"
        }
        "-a" = {
            value = "$http_auth_pair$"
            description = "Username:password on sites with basic authentication"
        }
        "--no-body" = {
            set_if = "$http_ignore_body$"
        }
        "-r" = "$http_expect_body_regex$"
        "-w" = "$http_warn_time$"
        "-c" = "$http_critical_time$"
        "-e" = "$http_expect$"
    }

    vars.http_address = "$address$"
    vars.http_ssl = false
    vars.http_sni = false
}

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#checkcommand :see: doc/09-object-types.md L65-L114 :see: lib/icinga/command.ti

Tags: Object type, Monitoring object type

timeout: int | None

Optional. The command timeout in seconds. Defaults to 1m.

https://github.com/Icinga/icinga2/blob/2c9117b4f71e00b2072e7dbe6c4ea4e48c882a87/lib/icinga/command.ti#L15-L17

execute: str | Function | None: https://github.com/Icinga/icinga2/blob/2c9117b4f71e00b2072e7dbe6c4ea4e48c882a87/lib/icinga/command.ti#L19

command: Sequence[str] | dict[str, Any] | None

Required. The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the “arguments” attribute this must be an array. Can be specified as function for advanced implementations.

https://github.com/Icinga/icinga2/blob/2c9117b4f71e00b2072e7dbe6c4ea4e48c882a87/lib/icinga/command.ti#L25-L28

Optional. A dictionary of command arguments.

https://github.com/Icinga/icinga2/blob/2c9117b4f71e00b2072e7dbe6c4ea4e48c882a87/lib/icinga/command.ti#L30-L46

env: Any | None

Optional. A dictionary of macros which should be exported as environment variables prior to executing the command.

https://github.com/Icinga/icinga2/blob/2c9117b4f71e00b2072e7dbe6c4ea4e48c882a87/lib/icinga/command.ti#L48-L51

vars: dict[str, Any] | None: Optional. A dictionary containing custom variables that are specific to this command.

class pretiac.object_types.Dependency(name: str | None = None, type: str | None = None, zone: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, package: str | None = None, templates: Sequence[str] | None = None, source_location: SourceLocation | None = None, active: bool | None = None, paused: bool | None = None, ha_mode: HAMode | None = None, original_attributes: dict[str, Any] | None = None, version: float | None = None, vars: dict[str, Any] | None = None, parent_host_name: str | None = None, parent_service_name: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, child_host_name: str | None = None, child_service_name: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, redundancy_group: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, disable_checks: bool | None = None, disable_notifications: bool | None = None, ignore_soft_states: bool | None = None, period: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, states: Sequence[str] | None = None)[source]

Bases: CustomVarObject

Dependency objects are used to specify dependencies between hosts and services. Dependencies can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service relations.

Service-to-Service Example:

object Dependency "webserver-internet" {
    parent_host_name = "internet"
    parent_service_name = "ping4"

    child_host_name = "webserver"
    child_service_name = "ping4"

    states = [ OK, Warning ]

    disable_checks = true
}

Host-to-Host Example:

object Dependency "webserver-internet" {
    parent_host_name = "internet"

    child_host_name = "webserver"

    states = [ Up ]

    disable_checks = true
}

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#dependency :see: doc/09-object-types.md L153-L258 https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/dependency.ti#L21-L99

Tags: Object type, Monitoring object type

parent_host_name: str | None: Required. The parent host.

parent_service_name: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]: Optional. The parent service. If omitted, this dependency object is treated as host dependency.

child_host_name: str | None: Required. The child host.

child_service_name: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]: Optional. The child service. If omitted, this dependency object is treated as host dependency.

redundancy_group: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]: Optional. Puts the dependency into a group of mutually redundant ones.

disable_checks: bool | None: Optional. Whether to disable checks (i.e., don’t schedule active checks and drop passive results) when this dependency fails. Defaults to false.

disable_notifications: bool | None: Optional. Whether to disable notifications when this dependency fails. Defaults to true.

ignore_soft_states: bool | None: Optional. Whether to ignore soft states for the reachability calculation. Defaults to true.

period: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]: Optional. Time period object during which this dependency is enabled.

states: Sequence[str] | None: Optional. A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.

class pretiac.object_types.Endpoint(name: str | None = None, type: str | None = None, zone: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, package: str | None = None, templates: Sequence[str] | None = None, source_location: SourceLocation | None = None, active: bool | None = None, paused: bool | None = None, ha_mode: HAMode | None = None, original_attributes: dict[str, Any] | None = None, version: float | None = None, host: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, port: int | None = None, log_duration: str | int | None = None, local_log_position: float | None = None, remote_log_position: float | None = None, icinga_version: int | None = None, capabilities: int | None = None, connecting: bool | None = None, syncing: bool | None = None, connected: bool | None = None, last_message_sent: float | None = None, last_message_received: float | None = None, messages_sent_per_second: float | None = None, messages_received_per_second: float | None = None, bytes_sent_per_second: float | None = None, bytes_received_per_second: float | None = None, messages_received_per_type: dict[Any, Any] | None = None, seconds_processing_messages: float | None = None)[source]

Bases: ConfigObject

Endpoint objects are used to specify connection information for remote Icinga 2 instances.

Example

object Endpoint "icinga2-agent1.localdomain" {
    host = "192.168.56.111"
    port = 5665
    log_duration = 1d
}

Example (disable replay log):

object Endpoint "icinga2-agent1.localdomain" {
    host = "192.168.5.111"
    port = 5665
    log_duration = 0
}

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#endpoint :see: doc/09-object-types.md L260-L293 https://github.com/Icinga/icinga2/blob/333534096ebc251de08cecd2f688bc690253902c/lib/remote/endpoint.ti#L12-L66

Tags: Object type, Monitoring object type

host: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]: The hostname/IP address of the remote Icinga 2 instance.

port: int | None: The service name/port of the remote Icinga 2 instance. Defaults to 5665.

log_duration: str | int | None: Optional. Duration for keeping replay logs on connection loss. Defaults to 1d (86400 seconds). Attribute is specified in seconds. If log_duration is set to 0, replaying logs is disabled. You could also specify the value in human readable format like 10m for 10 minutes or 1h for one hour.

local_log_position: float | None

remote_log_position: float | None

icinga_version: int | None

capabilities: int | None

connecting: bool | None

syncing: bool | None

connected: bool | None

last_message_sent: float | None

last_message_received: float | None

messages_sent_per_second: float | None

messages_received_per_second: float | None

bytes_sent_per_second: float | None

bytes_received_per_second: float | None

messages_received_per_type: dict[Any, Any] | None

seconds_processing_messages: float | None

class pretiac.object_types.EventCommand[source]

Bases: object

An event command definition.

object EventCommand "restart-httpd-event" {
    command = "/opt/bin/restart-httpd.sh"
}

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#eventcommand :see: doc/09-object-types.md L295-L320

Tags: Object type, Monitoring object type

class pretiac.object_types.Host(name: str | None = None, type: str | None = None, zone: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, package: str | None = None, templates: Sequence[str] | None = None, source_location: SourceLocation | None = None, active: bool | None = None, paused: bool | None = None, ha_mode: HAMode | None = None, original_attributes: dict[str, Any] | None = None, version: float | None = None, vars: dict[str, Any] | None = None, check_command: str | None = None, max_check_attempts: int | None = None, check_period: str | None = None, check_timeout: int | float | str | bool | Any | None = None, check_interval: float | None = None, retry_interval: float | None = None, event_command: str | None = None, volatile: bool | None = None, enable_active_checks: bool | None = None, enable_passive_checks: bool | None = None, enable_event_handler: bool | None = None, enable_notifications: bool | None = None, enable_flapping: bool | None = None, enable_perfdata: bool | None = None, flapping_ignore_states: Sequence[str] | None = None, flapping_threshold: float | None = None, flapping_threshold_low: float | None = None, flapping_threshold_high: float | None = None, notes: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, notes_url: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, action_url: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, icon_image: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, icon_image_alt: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, next_check: float | None = None, check_attempt: int | None = None, state_type: StateType | None = None, last_state_type: StateType | None = None, last_reachable: bool | None = None, last_check_result: CheckResult | None = None, last_state_change: float | None = None, last_hard_state_change: float | None = None, last_state_unreachable: float | None = None, previous_state_change: float | None = None, severity: int | None = None, problem: bool | None = None, handled: bool | None = None, next_update: float | None = None, force_next_check: bool | None = None, acknowledgement: int | None = None, acknowledgement_expiry: float | None = None, acknowledgement_last_change: float | None = None, force_next_notification: bool | None = None, last_check: float | None = None, downtime_depth: int | None = None, flapping_current: float | None = None, flapping_last_change: float | None = None, flapping: bool | None = None, command_endpoint: str | None = None, executions: Dictionary | None = None, groups: Sequence[str] | None = None, display_name: str | None = None, address: str | None = None, address6: str | None = None, state: HostState | None = None, last_state: HostState | None = None, last_hard_state: HostState | None = None, last_state_up: float | None = None, last_state_down: float | None = None)[source]

Bases: Checkable

A host.

object Host "icinga2-agent1.localdomain" {
    display_name = "Linux Client 1"
    address = "192.168.56.111"
    address6 = "2a00:1450:4001:815::2003"

    groups = [ "linux-servers" ]

    check_command = "hostalive"
}

See:: Icinga2 documentation: Host
See:: doc/09-object-types.md L323-L413
See:: lib/icinga/host.ti

Tags: Object type, Monitoring object type

groups: Sequence[str] | None

A list of host groups this host belongs to.

See:: lib/icinga/host.ti L18-L20

display_name: str | None

A short description of the host (e.g. displayed by external interfaces instead of the name if set).

See:: lib/icinga/host.ti L22-L30

address: str | None

The host’s IPv4 address. Available as command runtime macro $address$ if set.

See:: lib/icinga/host.ti L32

address6: str | None

The host’s IPv6 address. Available as command runtime macro $address6$ if set.

See:: lib/icinga/host.ti L33

state: HostState | None

The current state (0 = UP, 1 = DOWN).

See:: lib/icinga/host.ti L35-L37

last_state: HostState | None

The previous state (0 = UP, 1 = DOWN).

See:: lib/icinga/host.ti L38-L40

last_hard_state: HostState | None

The last hard state (0 = UP, 1 = DOWN).

See:: lib/icinga/host.ti L41-L43

last_state_up: float | None

When the last UP state occurred (as a UNIX timestamp).

See:: lib/icinga/host.ti L44

last_state_down: float | None

When the last DOWN state occurred (as a UNIX timestamp).

See:: lib/icinga/host.ti L45

class pretiac.object_types.HostGroup[source]

Bases: object

A group of hosts.

object HostGroup "linux-servers" {
    display_name = "Linux Servers"

    assign where host.vars.os == "Linux"
}

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#hostgroup :see: doc/09-object-types.md L417-L440

Tags: Object type, Monitoring object type

class pretiac.object_types.Notification[source]

Bases: object

Notification objects are used to specify how users should be notified in case of host and service state changes and other events.

Example:

object Notification "localhost-ping-notification" {
    host_name = "localhost"
    service_name = "ping4"

    command = "mail-notification"

    users = [ "user1", "user2" ] // reference to User objects

    types = [ Problem, Recovery ]
    states = [ Critical, Warning, OK ]
}

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#notification :see: doc/09-object-types.md L444-L527

Tags: Object type, Monitoring object type

class pretiac.object_types.NotificationCommand[source]

Bases: object

A notification command definition.

object NotificationCommand "mail-service-notification" {
    command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]

    arguments += {
        "-4" = {
            required = true
            value = "$notification_address$"
        }
        "-6" = "$notification_address6$"
        "-b" = "$notification_author$"
        "-c" = "$notification_comment$"
        "-d" = {
            required = true
            value = "$notification_date$"
        }
        "-e" = {
            required = true
            value = "$notification_servicename$"
        }
        "-f" = {
            value = "$notification_from$"
            description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
        }
        "-i" = "$notification_icingaweb2url$"
        "-l" = {
            required = true
            value = "$notification_hostname$"
        }
        "-n" = {
            required = true
            value = "$notification_hostdisplayname$"
        }
        "-o" = {
            required = true
            value = "$notification_serviceoutput$"
        }
        "-r" = {
            required = true
            value = "$notification_useremail$"
        }
        "-s" = {
            required = true
            value = "$notification_servicestate$"
        }
        "-t" = {
            required = true
            value = "$notification_type$"
        }
        "-u" = {
            required = true
            value = "$notification_servicedisplayname$"
        }
        "-v" = "$notification_logtosyslog$"
    }

    vars += {
        notification_address = "$address$"
        notification_address6 = "$address6$"
        notification_author = "$notification.author$"
        notification_comment = "$notification.comment$"
        notification_type = "$notification.type$"
        notification_date = "$icinga.long_date_time$"
        notification_hostname = "$host.name$"
        notification_hostdisplayname = "$host.display_name$"
        notification_servicename = "$service.name$"
        notification_serviceoutput = "$service.output$"
        notification_servicestate = "$service.state$"
        notification_useremail = "$user.email$"
        notification_servicedisplayname = "$service.display_name$"
    }
}

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#notificationcommand :see: doc/09-object-types.md L530-L622

Tags: Object type, Monitoring object type

class pretiac.object_types.ScheduledDowntime[source]

Bases: object

ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.

Example:

object ScheduledDowntime "some-downtime" {
    host_name = "localhost"
    service_name = "ping4"

    author = "icingaadmin"
    comment = "Some comment"

    fixed = false
    duration = 30m

    ranges = {
        "sunday" = "02:00-03:00"
    }
}

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#scheduleddowntime :see: doc/09-object-types.md L624-L674

Tags: Object type, Monitoring object type

class pretiac.object_types.Service(name: str | None = None, type: str | None = None, zone: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, package: str | None = None, templates: Sequence[str] | None = None, source_location: SourceLocation | None = None, active: bool | None = None, paused: bool | None = None, ha_mode: HAMode | None = None, original_attributes: dict[str, Any] | None = None, version: float | None = None, vars: dict[str, Any] | None = None, check_command: str | None = None, max_check_attempts: int | None = None, check_period: str | None = None, check_timeout: int | float | str | bool | Any | None = None, check_interval: float | None = None, retry_interval: float | None = None, event_command: str | None = None, volatile: bool | None = None, enable_active_checks: bool | None = None, enable_passive_checks: bool | None = None, enable_event_handler: bool | None = None, enable_notifications: bool | None = None, enable_flapping: bool | None = None, enable_perfdata: bool | None = None, flapping_ignore_states: Sequence[str] | None = None, flapping_threshold: float | None = None, flapping_threshold_low: float | None = None, flapping_threshold_high: float | None = None, notes: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, notes_url: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, action_url: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, icon_image: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, icon_image_alt: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, next_check: float | None = None, check_attempt: int | None = None, state_type: StateType | None = None, last_state_type: StateType | None = None, last_reachable: bool | None = None, last_check_result: CheckResult | None = None, last_state_change: float | None = None, last_hard_state_change: float | None = None, last_state_unreachable: float | None = None, previous_state_change: float | None = None, severity: int | None = None, problem: bool | None = None, handled: bool | None = None, next_update: float | None = None, force_next_check: bool | None = None, acknowledgement: int | None = None, acknowledgement_expiry: float | None = None, acknowledgement_last_change: float | None = None, force_next_notification: bool | None = None, last_check: float | None = None, downtime_depth: int | None = None, flapping_current: float | None = None, flapping_last_change: float | None = None, flapping: bool | None = None, command_endpoint: str | None = None, executions: Dictionary | None = None, groups: Sequence[str] | None = None, display_name: str | None = None, host_name: str | None = None, host: Host | None = None, state: ServiceState | None = None, last_state: ServiceState | None = None, last_hard_state: ServiceState | None = None, last_state_ok: float | None = None, last_state_warning: float | None = None, last_state_critical: float | None = None, last_state_unknown: float | None = None)[source]

Bases: Checkable

Service objects describe network services and how they should be checked by Icinga 2.

Best Practice

Rather than creating a Service object for a specific host it is usually easier to just create a Service template and use the apply keyword to assign the service to a float of hosts. Check the apply chapter for details.

Example:

object Service "uptime" {
    host_name = "localhost"

    display_name = "localhost Uptime"

    check_command = "snmp"

    vars.snmp_community = "public"
    vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"

    check_interval = 60s
    retry_interval = 15s

    groups = [ "all-services", "snmp" ]
}

Tags: Object type, Monitoring object type

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#service :see: lib/icinga/service.ti :see: doc/09-object-types.md L677-L781

groups: Sequence[str] | None: The service groups this service belongs to.

display_name: str | None

A short description of the service.

See:: doc/09-object-types.md L712
See:: lib/icinga/service.ti L34-L42

host_name: str | None: The host this service belongs to. There must be a Host object with that name.

host: Host | None

state: ServiceState | None: The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).

last_state: ServiceState | None: The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).

last_hard_state: ServiceState | None: The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).

last_state_ok: float | None: When the last OK state occurred (as a UNIX timestamp).

last_state_warning: float | None: When the last WARNING state occurred (as a UNIX timestamp).

last_state_critical: float | None: When the last CRITICAL state occurred (as a UNIX timestamp).

last_state_unknown: float | None: When the last UNKNOWN state occurred (as a UNIX timestamp).

class pretiac.object_types.ServiceGroup[source]

Bases: object

A group of services.

Example:

object ServiceGroup "snmp" {
    display_name = "SNMP services"
}

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#servicegroup :see: doc/09-object-types.md L784-L805

Tags: Object type, Monitoring object type

class pretiac.object_types.TimePeriodSegment(begin: int, end: int)[source]

Bases: object

See:: lib/icinga/timeperiod.cpp L84-L87

begin: int

end: int

Bases: CustomVarObject

Time periods can be used to specify when hosts/services should be checked or to limit when notifications should be sent out.

Examples:

object TimePeriod "nonworkhours" {
    display_name = "Icinga 2 TimePeriod for non working hours"

    ranges = {
        monday = "00:00-8:00,17:00-24:00"
        tuesday = "00:00-8:00,17:00-24:00"
        wednesday = "00:00-8:00,17:00-24:00"
        thursday = "00:00-8:00,17:00-24:00"
        friday = "00:00-8:00,16:00-24:00"
        saturday = "00:00-24:00"
        sunday = "00:00-24:00"
    }
}

object TimePeriod "exampledays" {
    display_name = "Icinga 2 TimePeriod for random example days"

    ranges = {
        //We still believe in Santa, no peeking!
        //Applies every 25th of December every year
        "december 25" = "00:00-24:00"

        //Any point in time can be specified,
        //but you still have to use a range
        "2038-01-19" = "03:13-03:15"

        //Evey 3rd day from the second monday of February
        //to 8th of November
        "monday 2 february - november 8 / 3" = "00:00-24:00"
    }
}

Additional examples can be found here.

Tags: Object type, Monitoring object type

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#timeperiod :see: doc/09-object-types.md L809-L869 :see: lib/icinga/timeperiod.ti L11-L39

display_name: str | None

A short description of the time period.

See:: lib/icinga/timeperiod.ti L13-L21

ranges: dict[str, str] | None

A dictionary containing information which days and durations apply to this timeperiod.

See:: lib/icinga/timeperiod.ti L22

update: dict[str, Any] | None

See:: lib/icinga/timeperiod.ti L23

prefer_includes: bool | None

Whether to prefer timeperiods includes or excludes. Default to true.

See:: lib/icinga/timeperiod.ti L24-L26

excludes: Sequence[str] | None

An array of timeperiods, which should exclude from your timerange.

See:: lib/icinga/timeperiod.ti L27-L29

includes: Sequence[str] | None

An array of timeperiods, which should include into your timerange.

See:: lib/icinga/timeperiod.ti L30-L32

valid_begin: float | None

See:: lib/icinga/timeperiod.ti L33

valid_end: float | None

See:: lib/icinga/timeperiod.ti L34

segments: Sequence[TimePeriodSegment] | None

See:: lib/icinga/timeperiod.ti L35

is_inside: bool | None

See:: lib/icinga/timeperiod.ti L36-L38

Bases: CustomVarObject

A user.

Example:

object User "icingaadmin" {
    display_name = "Icinga 2 Admin"
    groups = [ "icingaadmins" ]
    email = "icinga@localhost"
    pager = "icingaadmin@localhost.localdomain"

    period = "24x7"

    states = [ OK, Warning, Critical, Unknown ]
    types = [ Problem, Recovery ]

    vars.additional_notes = "This is the Icinga 2 Admin account."
}

Available notification state filters:

OK
Warning
Critical
Unknown
Up
Down

Available notification type filters:

DowntimeStart
DowntimeEnd
DowntimeRemoved
Custom
Acknowledgement
Problem
Recovery
FlappingStart
FlappingEnd

Tags: Object type, Monitoring object type

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#user :see: lib/icinga/user.ti :see: doc/09-object-types.md L872-L937

display_name: str | None

A short description of the user.

See:: lib/icinga/user.ti L14-L22
See:: doc/09-object-types.md L923

groups: Sequence[str] | None

An array of group names.

See:: lib/icinga/user.ti L23-L25
See:: doc/09-object-types.md L927

period: str | None

The name of a time period which determines when a notification for this user should be triggered. Not set by default (effectively 24x7).

See:: lib/icinga/user.ti L26-L30
See:: doc/09-object-types.md L929

types: Sequence[str] | None

A set of type filters when a notification for this user should be triggered. By default everything is matched.

See:: lib/icinga/user.ti L32
See:: doc/09-object-types.md L930

states: Sequence[str] | None

A set of state filters when a notification for this should be triggered. By default everything is matched.

See:: lib/icinga/user.ti L34
See:: doc/09-object-types.md L931

email: str | None

An email string for this user. Useful for notification commands.

See:: lib/icinga/user.ti L37
See:: doc/09-object-types.md L924

pager: str | None

A pager str for this user. Useful for notification commands.

See:: lib/icinga/user.ti L38
See:: doc/09-object-types.md L925

enable_notifications: bool | None

Whether notifications are enabled for this user. Defaults to true.

See:: lib/icinga/user.ti L40-L42
See:: doc/09-object-types.md L928

last_notification: float | None

When the last notification was sent for this user (as a UNIX timestamp).

See:: lib/icinga/user.ti L44
See:: doc/09-object-types.md L937

class pretiac.object_types.UserGroup(name: str | None = None, type: str | None = None, zone: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, package: str | None = None, templates: Sequence[str] | None = None, source_location: SourceLocation | None = None, active: bool | None = None, paused: bool | None = None, ha_mode: HAMode | None = None, original_attributes: dict[str, Any] | None = None, version: float | None = None, vars: dict[str, Any] | None = None, display_name: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, groups: Sequence[str] | None = None)[source]

Bases: CustomVarObject

A user group.

Example:

object UserGroup "icingaadmins" {
    display_name = "Icinga 2 Admin Group"
}

Tags: Object type, Monitoring object type

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#usergroup :see: doc/09-object-types.md L939-L960 https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/icinga/usergroup.ti#L10-L23

display_name: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]: Optional. A short description of the user group.

groups: Sequence[str] | None: Optional. An array of nested group names.

class pretiac.object_types.Zone(name: str | None = None, type: str | None = None, zone: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, package: str | None = None, templates: Sequence[str] | None = None, source_location: SourceLocation | None = None, active: bool | None = None, paused: bool | None = None, ha_mode: HAMode | None = None, original_attributes: dict[str, Any] | None = None, version: float | None = None, endpoints: Sequence[str] | None = None, parent: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)] = None, all_parents: Sequence[str] | None = None, is_global: bool | None = None)[source]

Bases: ConfigObject

Zone objects are used to specify which Icinga 2 instances are located in a zone.

Example:

object Zone "master" {
    endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
}

object Zone "satellite" {
    endpoints = [ "icinga2-satellite1.localdomain" ]
    parent = "master"
}

Tags: Object type, Monitoring object type

https://icinga.com/docs/icinga-2/latest/doc/09-object-types/#zone :see: doc/09-object-types.md L963-L989 https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/remote/zone.ti#L10-L23

endpoints: Sequence[str] | None: Optional. Array of endpoint names located in this zone.

parent: Annotated[str | None, BeforeValidator(func=_empty_str_to_none, json_schema_input_type=PydanticUndefined)]: Optional. The name of the parent zone. (Do not specify a global zone)

all_parents: Sequence[str] | None

is_global: bool | None: Optional. Whether configuration files for this zone should be synced to all endpoints. Defaults to false.

class pretiac.object_types.Comment[source]

Bases: object

Tags: Object type, Runtime object type

Bases: object

Downtimes created at runtime are represented as objects. You can create downtimes with the schedule-downtime API action.

Example:

object Downtime "my-downtime" {
    host_name = "localhost"
    author = "icingaadmin"
    comment = "This is a downtime."
    start_time = 1505312869
    end_time = 1505312924
}

Tags: Object type, Runtime object type

See:: doc/09-object-types/#downtime

host_name: str | None: Required. The name of the host this downtime belongs to.

service_name: str | None: Optional. The short name of the service this downtime belongs to. If omitted, this downtime object is treated as host downtime.

author: str | None: Required. The author’s name.

comment: str | None: Required. The comment text.

start_time: float | None: Required. The start time as UNIX timestamp.

end_time: float | None: Timestamp Required. The end time as UNIX timestamp.

duration: int | None: Number Optional. The duration as number.

entry_time: float | None: Timestamp Optional. The UNIX timestamp when this downtime was added.

fixed: bool | None: Boolean Optional. Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the advanced topics chapter.

triggers: Sequence[str] | None: Array of object names

class pretiac.object_types.ApiListener[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.CheckerComponent[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.CompatLogger[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.ElasticsearchWriter[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.ExternalCommandListener[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.FileLogger[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.GelfWriter[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.GraphiteWriter[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.IcingaApplication[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.IcingaDB[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.IdoMySqlConnection[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.IdoPgsqlConnection[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.InfluxdbWriter[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.Influxdb2Writer[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.JournaldLogger[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.LiveStatusListener[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.NotificationComponent[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.OpenTsdbWriter[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.PerfdataWriter[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.SyslogLogger[source]

Bases: object

Tags: Object type, Feature object type

class pretiac.object_types.WindowsEventLogLogger[source]

Bases: object

Tags: Object type, Feature object type

pretiac.object_types.EventStreamType

See:: doc/12-icinga2-api/#event-stream-types
See:: lib/icinga/apievents.hpp L16-L47
See:: lib/remote/eventshandler.cpp L22-L38

alias of Literal[‘CheckResult’, ‘StateChange’, ‘Notification’, ‘AcknowledgementSet’, ‘AcknowledgementCleared’, ‘CommentAdded’, ‘CommentRemoved’, ‘DowntimeAdded’, ‘DowntimeRemoved’, ‘DowntimeStarted’, ‘DowntimeTriggered’, ‘ObjectCreated’, ‘ObjectDeleted’, ‘ObjectModified’]

class pretiac.object_types.EventStreamTypeCheckResult(type: Literal['CheckResult'], timestamp: float, host: str, check_result: CheckResult, downtime_depth: float, acknowledgement: bool, service: str | None = None)[source]

Bases: object

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-checkresult

type: Literal['CheckResult']

timestamp: float: Unix timestamp when the event happened.

host: str: Host name.

check_result: CheckResult: Serialized CheckResult value type.

downtime_depth: float: Amount of active downtimes on the checkable.

acknowledgement: bool: Whether the object is acknowledged.

service: str | None: Service name. Optional if this is a host check result.

class pretiac.object_types.EventStreamTypeStateChange(type: Literal['StateChange'])[source]

Bases: object

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-statechange

type: Literal['StateChange']

class pretiac.object_types.EventStreamTypeNotification(type: Literal['Notification'])[source]

Bases: object

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-notification

type: Literal['Notification']

class pretiac.object_types.EventStreamTypeFlapping(type: Literal['Flapping'])[source]

Bases: object

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-flapping

type: Literal['Flapping']

class pretiac.object_types.EventStreamTypeAcknowledgementSet(type: Literal['AcknowledgementSet'])[source]

Bases: object

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-acknowledgementset

type: Literal['AcknowledgementSet']

class pretiac.object_types.EventStreamTypeAcknowledgementCleared(type: Literal['AcknowledgementCleared'])[source]

Bases: object

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-acknowledgementcleared

type: Literal['AcknowledgementCleared']

class pretiac.object_types.EventStreamTypeCommentAdded(timestamp: float, comment: Comment, type: Literal['CommentAdded'])[source]

Bases: _EventStreamTypeComment

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-commentadded

type: Literal['CommentAdded']

class pretiac.object_types.EventStreamTypeCommentRemoved(timestamp: float, comment: Comment, type: Literal['CommentRemoved'])[source]

Bases: _EventStreamTypeComment

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-commentremoved

type: Literal['CommentRemoved']

class pretiac.object_types.EventStreamTypeDowntimeAdded(timestamp: float, downtime: Downtime, type: Literal['DowntimeAdded'])[source]

Bases: _EventStreamTypeDowntime

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-downtimeadded

type: Literal['DowntimeAdded']

class pretiac.object_types.EventStreamTypeDowntimeRemoved(timestamp: float, downtime: Downtime, type: Literal['DowntimeRemoved'])[source]

Bases: _EventStreamTypeDowntime

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-downtimeremoved

type: Literal['DowntimeRemoved']

class pretiac.object_types.EventStreamTypeDowntimeStarted(timestamp: float, downtime: Downtime, type: Literal['DowntimeStarted'])[source]

Bases: _EventStreamTypeDowntime

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-downtimestarted

type: Literal['DowntimeStarted']

class pretiac.object_types.EventStreamTypeDowntimeTriggered(timestamp: float, downtime: Downtime, type: Literal['DowntimeTriggered'])[source]

Bases: _EventStreamTypeDowntime

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#event-stream-type-downtimetriggered

type: Literal['DowntimeTriggered']

Bases: object

lib/base/perfdatavalue.ti L8-L18 lib/base/perfdatavalue.hpp L17-L36

label: str

value: float

counter: bool

unit: str

crit: int | float | str | bool | Any | None

warn: int | float | str | bool | Any | None

min: int | float | str | bool | Any | None

max: int | float | str | bool | Any | None

class pretiac.object_types.StatusMessage(name: str, status: dict[str, Any], perfdata: Sequence[PerfdataValue] | None)[source]

Bases: object

See:: lib/remote/statushandler.cpp L53-L57

name: str

status: dict[str, Any]

perfdata: Sequence[PerfdataValue] | None

class pretiac.object_types.ConfigPackage(name: str, stages: Sequence[str], active_stage: str)[source]

Bases: object

https://github.com/Icinga/icinga2/blob/c0b047b1aab6de3c5e51fdeb63d3bf4236f7fa6d/lib/remote/configpackageshandler.cpp#L75-L79

name: str

stages: Sequence[str]

active_stage: str

class pretiac.object_types.ConfigFile(name: str, type: Literal['directory', 'file'])[source]

Bases: object

name: str

type: Literal['directory', 'file']

class pretiac.object_types.ConfigPackageStageFiles(package: str, stage: str, files: Sequence[ConfigFile])[source]

Bases: object

package: str

stage: str

files: Sequence[ConfigFile]

class pretiac.object_types.TypeFieldAttributeInfo(config: bool, state: bool, required: bool, navigation: bool, no_user_modify: bool, no_user_view: bool, deprecated: bool)[source]

Bases: object

https://github.com/Icinga/icinga2/blob/8beb0b74ab9f8402abf4a05b9b768d312304e3f0/lib/remote/typequeryhandler.cpp#L136-L144

config: bool

state: bool

required: bool

navigation: bool

no_user_modify: bool

no_user_view: bool

deprecated: bool

class pretiac.object_types.TypeFieldInfo(id: int, type: Literal['Array', 'Boolean', 'CheckResult', 'Dictionary', 'Function', 'Host', 'Namespace', 'Number', 'Object', 'Service', 'String', 'Timestamp', 'Type', 'uint_fast64_t', 'unsigned long', 'unsigned short', 'Value'], array_rank: int, attributes: TypeFieldAttributeInfo, ref_type: str | None = None, navigation_name: str | None = None)[source]

Bases: object

https://github.com/Icinga/icinga2/blob/8beb0b74ab9f8402abf4a05b9b768d312304e3f0/lib/remote/typequeryhandler.cpp#L122-L145

id: int

type: Literal['Array', 'Boolean', 'CheckResult', 'Dictionary', 'Function', 'Host', 'Namespace', 'Number', 'Object', 'Service', 'String', 'Timestamp', 'Type', 'uint_fast64_t', 'unsigned long', 'unsigned short', 'Value']

array_rank: int

attributes: TypeFieldAttributeInfo

ref_type: str | None

navigation_name: str | None

class pretiac.object_types.TypeInfo(name: str, plural_name: str, abstract: bool, fields: dict[str, TypeFieldInfo], prototype_keys: Sequence[str], base: str | None = None)[source]

Bases: object

https://github.com/Icinga/icinga2/blob/8beb0b74ab9f8402abf4a05b9b768d312304e3f0/lib/remote/typequeryhandler.cpp#L49-L156

name: str

plural_name: str

abstract: bool

fields: dict[str, TypeFieldInfo]

prototype_keys: Sequence[str]

base: str | None

class pretiac.object_types.Variable(name: str, type: Literal['Array', 'Boolean', 'CheckResult', 'Dictionary', 'Function', 'Host', 'Namespace', 'Number', 'Object', 'Service', 'String', 'Timestamp', 'Type', 'uint_fast64_t', 'unsigned long', 'unsigned short', 'Value'], value: Any)[source]

Bases: object

https://github.com/Icinga/icinga2/blob/b62326d30cb1329ff3c5f8cf47ec0d3213b83cae/lib/remote/variablequeryhandler.cpp#L24-L28

name: str

type: Literal['Array', 'Boolean', 'CheckResult', 'Dictionary', 'Function', 'Host', 'Namespace', 'Number', 'Object', 'Service', 'String', 'Timestamp', 'Type', 'uint_fast64_t', 'unsigned long', 'unsigned short', 'Value']

value: Any

pretiac.raw_client

Icinga 2 API client

The Icinga 2 API allows you to manage configuration objects and resources in a simple, programmatic way using HTTP requests.

pretiac.raw_client.assemble_payload(**kwargs: Any) → dict[str, Any][source]

class pretiac.raw_client.Result(code: int, status: str)[source]

Bases: object

code: int

status: str

class pretiac.raw_client.ResultContainer(results: list[Result])[source]

Bases: object

results: list[Result]

class pretiac.raw_client.ObjectsUrlEndpoint(client: RawClient)[source]

Bases: RequestHandler

Connects to the URL endpoint objects of the Icinga2 API.

Provides methods to manage configuration objects:

creating objects
querying objects
modifying objects
deleting objects

path_prefix: for example objects for localhost:5665/v1/objects

list(object_type: Literal['ApiUser', 'CheckCommand', 'Dependency', 'Endpoint', 'EventCommand', 'Host', 'HostGroup', 'Notification', 'NotificationCommand', 'ScheduledDowntime', 'Service', 'ServiceGroup', 'TimePeriod', 'User', 'UserGroup', 'Zone', 'Comment', 'Downtime', 'ApiListener', 'CheckerComponent', 'CompatLogger', 'ElasticsearchWriter', 'ExternalCommandListener', 'FileLogger', 'GelfWriter', 'GraphiteWriter', 'IcingaApplication', 'IcingaDB', 'IdoMySqlConnection', 'IdoPgsqlConnection', 'InfluxdbWriter', 'Influxdb2Writer', 'JournaldLogger', 'LiveStatusListener', 'NotificationComponent', 'OpenTsdbWriter', 'PerfdataWriter', 'SyslogLogger', 'WindowsEventLogLogger'], name: str | None = None, attrs: Sequence[str] | None = None, filters: str | None = None, filter_vars: dict[str, Any] | None = None, joins: bool | Sequence[str] | None = None, suppress_exception: bool | None = None) → Any[source]

get object by type or name

Parameters:

object_type – The type of the object, for example Service, Host or User.
name – The full object name, for example example.localdomain or example.localdomain!http.
attrs – only return these attributes
filters – filters matched object(s)
filter_vars – variables used in the filters expression
joins – show joined object
suppress_exception – If this parameter is set to True, no exceptions are thrown.

Get all hosts:

raw_client.objects.list("Host")

List the service ping4 of host webserver01.domain!ping4:

raw_client.objects.list("Service", "webserver01.domain!ping4")

Get all hosts but limit attributes to address and state:

raw_client.objects.list("Host", attrs=["address", "state"])

Get all hosts which have webserver in their host name:

raw_client.objects.list("Host", filters='match("webserver*", host.name)')

Get all services and the joined host name:

raw_client.objects.list("Service", joins=["host.name"])

Get all services and all supported joins:

raw_client.objects.list("Service", joins=True)

Get all services which names start with vHost and are assigned to hosts named webserver* using filter_vars:

hostname_pattern = "webserver*"
service_pattern = "vHost*"
raw_client.objects.list(
    "Service",
    filters="match(hpattern, host.name) && match(spattern, service.name)",
    filter_vars={"hpattern": hostname_pattern, "spattern": service_pattern},
)

See:: Icinga2 API documentation: doc/12-icinga2-api/#querying-objects

get(object_type: Literal['ApiUser', 'CheckCommand', 'Dependency', 'Endpoint', 'EventCommand', 'Host', 'HostGroup', 'Notification', 'NotificationCommand', 'ScheduledDowntime', 'Service', 'ServiceGroup', 'TimePeriod', 'User', 'UserGroup', 'Zone', 'Comment', 'Downtime', 'ApiListener', 'CheckerComponent', 'CompatLogger', 'ElasticsearchWriter', 'ExternalCommandListener', 'FileLogger', 'GelfWriter', 'GraphiteWriter', 'IcingaApplication', 'IcingaDB', 'IdoMySqlConnection', 'IdoPgsqlConnection', 'InfluxdbWriter', 'Influxdb2Writer', 'JournaldLogger', 'LiveStatusListener', 'NotificationComponent', 'OpenTsdbWriter', 'PerfdataWriter', 'SyslogLogger', 'WindowsEventLogLogger'], name: str, attrs: Sequence[str] | None = None, joins: bool | Sequence[str] | None = None, suppress_exception: bool | None = None) → Any[source]

Get a single object (Host, Service, …).

Parameters:

object_type – The type of the object, for example Service, Host or User.
name – The full object name, for example example.localdomain or example.localdomain!http.
attrs – Get only the specified objects attributes.
joins – Also get the joined object, e.g. for a Service the Host object.
suppress_exception – If this parameter is set to True, no exceptions are thrown.

Get host webserver01.domain:

raw_client.objects.get("Host", "webserver01.domain")

Get service ping4 of host webserver01.domain:

raw_client.objects.get("Service", "webserver01.domain!ping4")

Get host webserver01.domain but the attributes address and state:

raw_client.objects.get(
    "Host", "webserver01.domain", attrs=["address", "state"]
)

Get service ping4 of host webserver01.domain and the host attributes:

raw_client.objects.get("Service", "webserver01.domain!ping4", joins=True)

See:: Icinga2 API documentation: doc/12-icinga2-api/#querying-objects

create(object_type: Literal['ApiUser', 'CheckCommand', 'Dependency', 'Endpoint', 'EventCommand', 'Host', 'HostGroup', 'Notification', 'NotificationCommand', 'ScheduledDowntime', 'Service', 'ServiceGroup', 'TimePeriod', 'User', 'UserGroup', 'Zone', 'Comment', 'Downtime', 'ApiListener', 'CheckerComponent', 'CompatLogger', 'ElasticsearchWriter', 'ExternalCommandListener', 'FileLogger', 'GelfWriter', 'GraphiteWriter', 'IcingaApplication', 'IcingaDB', 'IdoMySqlConnection', 'IdoPgsqlConnection', 'InfluxdbWriter', 'Influxdb2Writer', 'JournaldLogger', 'LiveStatusListener', 'NotificationComponent', 'OpenTsdbWriter', 'PerfdataWriter', 'SyslogLogger', 'WindowsEventLogLogger'], name: str, templates: Sequence[str] | None = None, attrs: dict[str, Any] | None = None, suppress_exception: bool | None = None) → Any[source]

Create an object using templates and specify attributes (attrs).

Parameters:

object_type – The type of the object, for example Service, Host or User.
name – The full object name, for example example.localdomain or example.localdomain!http.
templates – Import existing configuration templates for this object type. Note: These templates must either be statically configured or provided in config packages.
attrs – Set specific object attributes for this object type.
suppress_exception – If this parameter is set to True, no exceptions are thrown.

Create a host:

raw_client.objects.create(
    "Host", "localhost", ["generic-host"], {"address": "127.0.0.1"}
)

Create a service for Host localhost:

raw_client.objects.create(
    "Service",
    "testhost3!dummy",
    {"check_command": "dummy"},
    ["generic-service"],
)

See:: Icinga2 API documentation: doc/12-icinga2-api/#creating-config-objects

update(object_type: Literal['ApiUser', 'CheckCommand', 'Dependency', 'Endpoint', 'EventCommand', 'Host', 'HostGroup', 'Notification', 'NotificationCommand', 'ScheduledDowntime', 'Service', 'ServiceGroup', 'TimePeriod', 'User', 'UserGroup', 'Zone', 'Comment', 'Downtime', 'ApiListener', 'CheckerComponent', 'CompatLogger', 'ElasticsearchWriter', 'ExternalCommandListener', 'FileLogger', 'GelfWriter', 'GraphiteWriter', 'IcingaApplication', 'IcingaDB', 'IdoMySqlConnection', 'IdoPgsqlConnection', 'InfluxdbWriter', 'Influxdb2Writer', 'JournaldLogger', 'LiveStatusListener', 'NotificationComponent', 'OpenTsdbWriter', 'PerfdataWriter', 'SyslogLogger', 'WindowsEventLogLogger'], name: str, attrs: dict[str, Any], suppress_exception: bool | None = None) → Any[source]

Update an object with the specified attributes.

Parameters:

object_type – The type of the object, for example Service, Host or User.
name – the name of the object
attrs – object’s attributes to change
suppress_exception – If this parameter is set to True, no exceptions are thrown.

Change the ip address of a host:

raw_client.objects.update("Host", "localhost", {"address": "127.0.1.1"})

Update a service and change the check interval:

raw_client.objects.update(
    "Service", "testhost3!dummy", {"check_interval": "10m"}
)

See:: Icinga2 API documentation: doc/12-icinga2-api/#modifying-objects

delete(object_type: Literal['ApiUser', 'CheckCommand', 'Dependency', 'Endpoint', 'EventCommand', 'Host', 'HostGroup', 'Notification', 'NotificationCommand', 'ScheduledDowntime', 'Service', 'ServiceGroup', 'TimePeriod', 'User', 'UserGroup', 'Zone', 'Comment', 'Downtime', 'ApiListener', 'CheckerComponent', 'CompatLogger', 'ElasticsearchWriter', 'ExternalCommandListener', 'FileLogger', 'GelfWriter', 'GraphiteWriter', 'IcingaApplication', 'IcingaDB', 'IdoMySqlConnection', 'IdoPgsqlConnection', 'InfluxdbWriter', 'Influxdb2Writer', 'JournaldLogger', 'LiveStatusListener', 'NotificationComponent', 'OpenTsdbWriter', 'PerfdataWriter', 'SyslogLogger', 'WindowsEventLogLogger'], name: str | None = None, filters: str | None = None, filter_vars: dict[str, Any] | None = None, cascade: bool = True, suppress_exception: bool | None = None) → Any[source]

Delete an object.

Parameters:

object_type – The type of the object, for example Service, Host or User.
name – The full object name, for example example.localdomain or example.localdomain!http.
filters – filters matched object(s)
filter_vars – variables used in the filters expression
cascade – Delete objects depending on the deleted objects (e.g. services on a host).
suppress_exception – If this parameter is set to True, no exceptions are thrown.

Delete the localhost:

raw_client.objects.delete("Host", "localhost")

Delete all services matching vhost*:

raw_client.objects.delete(
    "Service", filters='match("vhost*", service.name)'
)

See:: Icinga2 API documentation: doc/12-icinga2-api/#deleting-objects

class pretiac.raw_client.ActionsUrlEndpoint(client: RawClient)[source]

Bases: RequestHandler

Connects to the URL endpoint actions of the Icinga2 API.

There are several actions available for Icinga 2 provided by the /v1/actions URL endpoint.

The following actions are also used by Icinga Web 2:

sending check results to Icinga from scripts, remote agents, etc.
scheduling downtimes from external scripts or cronjobs
acknowledging problems
adding comments

https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#actions

path_prefix: for example objects for localhost:5665/v1/objects

Process a check result for a host or a service.

Send a POST request to the URL endpoint actions/process-check-result.

Parameters:

type – Host or Service.
name – The name of the object.
exit_status – For services: 0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN, for hosts: 0=UP, 1=DOWN.
plugin_output – One or more lines of the plugin main output. Does not contain the performance data.
check_command – The first entry should be the check commands path, then one entry for each command line option followed by an entry for each of its argument. Alternativly a single string can be used.
check_source – Usually the name of the command_endpoint.
execution_start – The timestamp where a script/process started its execution.
execution_end – The timestamp where a script/process ended its execution. This timestamp is used in features to determine e.g. the metric timestamp.
ttl – Time-to-live duration in seconds for this check result. The next expected check result is now + ttl where freshness checks are executed.
filter – filters matched object(s)
filter_vars – variables used in the filters expression
suppress_exception – If this parameter is set to True, no exceptions are thrown.

Returns:

the response as json

raw_client.process_check_result(
    "Service",
    "myhost.domain!ping4",
    exit_status=2,
    plugin_output="PING CRITICAL - Packet loss = 100%",
    performance_data=[
        "rta=5000.000000ms;3000.000000;5000.000000;0.000000",
        "pl=100%;80;100;0",
    ],
    check_source="python client",
)

See:: Icinga2 API documentation: doc/12-icinga2-api/#process-check-result

reschedule_check(object_type: Literal['Host', 'Service'], filters: str, filter_vars: dict[str, Any] | None = None, next_check: int | None = None, force_check: bool | None = True) → Any[source]

Reschedule a check for hosts and services.

example 1:

raw_client.reschedule_check("Service", 'service.name=="ping4"')

example 2:

raw_client.reschedule_check("Host", 'host.name=="localhost"', 1577833200)

Parameters:

object_type – Host or Service
filters – filters matched object(s)
filter_vars – variables used in the for filters expression
next_check – timestamp to run the check
force – ignore period restrictions and disabled checks

Returns:

the response as json

See:

Icinga2 API documentation: doc/12-icinga2-api/#reschedule-check

send_custom_notification(object_type: Literal['Host', 'Service'], filters: str, author: str, comment: str, filter_vars: dict[str, Any] | None = None, force: int | None = False) → Any[source]

Send a custom notification for hosts and services.

example 1:

send_custom_notification(
    "Host", "host.name==localhost", "icingaadmin", "test comment"
)

Parameters:

object_type – Host or Service
filters – filters matched object
author – name of the author
comment – comment text
force – ignore downtimes and notification settings
filter_vars – variables used in the filters expression

Returns:

the response as json

See:

Icinga2 API documentation: doc/12-icinga2-api/#send-custom-notification

delay_notification(object_type: Literal['Host', 'Service'], filters: str, timestamp: int, filter_vars: dict[str, Any] | None = None) → Any[source]

Delay notifications for a host or a service.

example 1:

delay_notification("Service", "1446389894")

delay_notification("Host", 'host.name=="localhost"', "1446389894")

Parameters:

object_type – Host or Service
filters – filters matched object(s)
timestamp – timestamp to delay the notifications to
filter_vars – variables used in the filters expression

Returns:

the response as json

See:

Icinga2 API documentation: doc/12-icinga2-api/#delay-notification

acknowledge_problem(object_type: Literal['Host', 'Service'], filters: str, author: str, comment: str, filter_vars: dict[str, Any] | None = None, expiry: int | None = None, sticky: bool | None = None, notify: bool | None = None, persistent: bool | None = None) → Any[source]

Acknowledge a Service or Host problem.

Parameters:

object_type – Host or Service
filters – filters matched object(s)
author – name of the author
comment – comment text
filter_vars – variables used in the filters expression
expiry – acknowledgement expiry timestamp
sticky – stay till full problem recovery
notify – send notification
persistent – the comment will remain after the acknowledgement recovers or expires

Returns:

the response as json

See:

Icinga2 API documentation: doc/12-icinga2-api/#acknowledge-problem

remove_acknowledgement(object_type: Literal['Host', 'Service'], filters: str, filter_vars: dict[str, Any] | None = None) → Any[source]

Remove the acknowledgement for services or hosts.

example 1:

raw_client.actions.remove_acknowledgement(
    object_type="Service", filters="service.state==2"
)

Parameters:

object_type – Host or Service
filters – filters matched object(s)
filter_vars – variables used in the filters expression

Returns:

the response as json

See:

Icinga2 API documentation: doc/12-icinga2-api/#remove-acknowledgement

add_comment(object_type: Literal['Host', 'Service'], filter: str, author: str, comment: str, filter_vars: dict[str, Any] | None = None) → Any[source]

Add a comment from an author to services or hosts.

example 1:

raw_client.actions.add_comment(
    "Service",
    'service.name=="ping4"',
    "icingaadmin",
    "Troubleticket #123456789 opened.",
)

Parameters:

object_type – The valid types for this action are Host and Service.
filter – filters matched object(s)
author – name of the author
comment – comment text
filter_vars – variables used in the filters expression

Returns:

the response as json

See:

Icinga2 API documentation: doc/12-icinga2-api/#add-comment

remove_comment(object_type: Literal['Host', 'Service'], name: str | None = None, filters: str | None = None, filter_vars: dict[str, Any] | None = None) → Any[source]

Remove a comment using its name or filters.

example 1:

remove_comment("Commentlocalhost!localhost-1458202056-25")

example 2:

remove_comment('Service'
            filters='service.name=="ping4"')

Parameters:

object_type – Host, Service or Comment
name – name of the Comment
filters – filters matched object(s)
filter_vars – variables used in the filters expression

Returns:

the response as json

See:

Icinga2 API documentation: doc/12-icinga2-api/#remove-comment

schedule_downtime(object_type: Literal['Host', 'Service'], filters: str, author: str, comment: str, start_time: int, end_time: int, duration: int, filter_vars: dict[str, Any] | None = None, fixed: bool | None = None, all_services: bool | None = None, trigger_name: str | None = None, child_options: str | None = None) → Any[source]

Schedule a downtime for hosts and services.

example 1:

schedule_downtime(
    'object_type': 'Service',
    'filters': r'service.name=="ping4"',
    'author': 'icingaadmin',
    'comment': 'IPv4 network maintenance',
    'start_time': 1446388806,
    'end_time': 1446389806,
    'duration': 1000
)

example 2:

schedule_downtime(
    'object_type': 'Host',
    'filters': r'match("*", host.name)',
    'author': 'icingaadmin',
    'comment': 'IPv4 network maintenance',
    'start_time': 1446388806,
    'end_time': 1446389806,
    'duration': 1000
)

Parameters:

object_type – Host or Service
filters – filters matched object(s)
author – name of the author
comment – comment text
start_time – timestamp marking the beginning
end_time – timestamp marking the end
duration – duration of the downtime in seconds
filter_vars – variables used in the filters expression
fixed – fixed or flexible downtime
all_services – sets downtime for all services for the matched host objects
trigger_name – trigger for the downtime
child_options – schedule child downtimes.

Returns:

the response as json

See:

Icinga2 API documentation: doc/12-icinga2-api/#schedule-downtime

remove_downtime(object_type: Literal['Host', 'Service'], name: str | None = None, filters: str | None = None, filter_vars: dict[str, Any] | None = None) → Any[source]

Remove the downtime using its name or filters.

example 1:

remove_downtime("Downtime", "localhost!ping4!localhost-1458148978-14")

example 2:

remove_downtime("Service", filters='service.name=="ping4"')

Parameters:

object_type – Host, Service or Downtime
name – name of the downtime
filters – filters matched object(s)
filter_vars – variables used in the filters expression

Returns:

the response as json

See:

Icinga2 API documentation: doc/12-icinga2-api/#remove-downtime

shutdown_process() → Any[source]

Shuts down Icinga2. May or may not return.

example 1:

shutdown_process()

See:: Icinga2 API documentation: doc/12-icinga2-api/#shutdown-process

restart_process() → Any[source]

Restarts Icinga2. May or may not return.

example 1:

restart_process()

See:: Icinga2 API documentation: doc/12-icinga2-api/#restart-process

generate_ticket(cn: str) → Any[source]

Generates a PKI ticket for CSR auto-signing. This can be used in combination with satellite/client setups requesting this ticket number.

Example:

raw_client.actions.generate_ticket("my-server-name")

Parameters:: cn – Required. The host’s common name for which the ticket should be generated.
See:: Icinga2 API documentation: doc/12-icinga2-api/#generate-ticket

class pretiac.raw_client.EventsUrlEndpoint(client: RawClient)[source]

Bases: RequestHandler

Connects to the URL endpoint events of the Icinga2 API.

path_prefix: for example objects for localhost:5665/v1/objects

subscribe(types: Sequence[Literal['CheckResult', 'StateChange', 'Notification', 'AcknowledgementSet', 'AcknowledgementCleared', 'CommentAdded', 'CommentRemoved', 'DowntimeAdded', 'DowntimeRemoved', 'DowntimeStarted', 'DowntimeTriggered', 'ObjectCreated', 'ObjectDeleted', 'ObjectModified']], queue: str, filter: str | None = None, filter_vars: dict[str, Any] | None = None) → Generator[str | Any, Any, None][source]

Subscribe to an event stream.

Event streams can be used to receive check results, downtimes, comments, acknowledgements, etc. as a “live stream” from Icinga.

You can for example forward these types into your own backend. Process the metrics and correlate them with notifications and state changes e.g. in Elasticsearch with the help of Icingabeat. Another use case are aligned events and creating/resolving tickets automatically in your ticket system.

You can subscribe to event streams by sending a POST request to the URL endpoint /v1/events. The following parameters need to be specified (either as URL parameters or in a JSON-encoded message body):

example 1:

types = ["CheckResult"]
queue = "monitor"
filters = "event.check_result.exit_status==2"
for event in subscribe(types, queue, filters):
    print event

Parameters:

types – Required. Event type(s). Multiple types as URL parameters are supported.
queue – Required. Unique queue name. Multiple HTTP clients can use the same queue as long as they use the same event types and filter.
filter – Filter for specific event attributes using filter expressions.
filter_vars – variables used in the filters expression

Returns:

the events

See:

Icinga2 API documentation: doc/12-icinga2-api/#event-streams

class pretiac.raw_client.StatusUrlEndpoint(client: RawClient)[source]

Bases: RequestHandler

Connects to the URL endpoint status of the Icinga2 API.

See:: lib/remote/statushandler.cpp:

path_prefix: for example objects for localhost:5665/v1/objects

list(status_type: Literal['ApiListener', 'CIB', 'CheckerComponent', 'ElasticsearchWriter', 'FileLogger', 'GelfWriter', 'GraphiteWriter', 'IcingaApplication', 'IdoMysqlConnection', 'IdoPgsqlConnection', 'Influxdb2Writer', 'InfluxdbWriter', 'JournaldLogger', 'NotificationComponent', 'OpenTsdbWriter', 'PerfdataWriter', 'SyslogLogger'] | str | None = None) → Any[source]

Retrieve status information and statistics for Icinga 2.

List complete status:

.. code-block:: python

client.status.list()

List the status of the core application:

client.status.list("IcingaApplication")

Parameters:: status_type – Limit the output by specifying a status type, e.g. IcingaApplication.
Returns:: status information
See:: doc/12-icinga2-api/#status-and-statistics

class pretiac.raw_client.ConfigUrlEndpoint(client: RawClient)[source]

Bases: RequestHandler

Connects to the URL endpoint config of the Icinga2 API.

Manage configuration packages and stages based on configuration files and directory trees.

path_prefix: for example objects for localhost:5665/v1/objects

create_package(package_name: str, suppress_exception: bool | None = None) → Any[source]

Create a new empty configuration package.

Parameters:

package_name – Package names with the _ prefix are reserved for internal packages and must not be used. You can recognize _api, _etc and _cluster when querying specific objects and packages.
suppress_exception – If this parameter is set to True, no exceptions are thrown.

See:

Icinga2 API documentation: doc/12-icinga2-api/#create-a-config-package

create_stage(package_name: str, files: dict[str, str], reload: bool | None = None, activate: bool | None = None, suppress_exception: bool | None = None) → Any[source]

Configuration files in packages are managed in stages. Stages provide a way to maintain multiple configuration versions for a package. Once a new stage is deployed, the content is validated and set as active stage on success.

On failure, the older stage remains active, and the caller can fetch the startup.log from this stage deployment attempt to see what exactly failed. You can see that in the Director’s deployment log.

Parameters:

package_name – Package names with the _ prefix are reserved for internal packages and must not be used. You can recognize _api, _etc and _cluster when querying specific objects and packages.
files – Dictionary of file targets and their content.
reload – Tell icinga2 to reload after stage config validation (defaults to true).
activate – Tell icinga2 to activate the stage if it validates (defaults to true). If activate is set to false, reload must also be false.
suppress_exception – If this parameter is set to True, no exceptions are thrown.

Example for a local configuration in the conf.d directory:

raw_client.configuration.create_stage(
    package_name="example-cmdb",
    files={
        "conf.d/test-host.conf": 'object Host "test-host" { address = "127.0.0.1", check_command = "hostalive" }'
    },
)

Example for a host configuration inside the satellite zone in the zones.d directory:

raw_client.configuration.create_stage(
    package_name="example-cmdb",
    files={
        "zones.d/satellite/host2.conf": 'object Host "satellite-host" { address = "192.168.1.100", check_command = "hostalive"',
    },
)

See:: Icinga2 API documentation: doc/12-icinga2-api/#create-a-stage-upload-configuration

list_packages(suppress_exception: bool | None = None) → Any[source]

List packages and their stages.

Parameters:: suppress_exception – If this parameter is set to True, no exceptions are thrown.
See:: Icinga2 API documentation: doc/12-icinga2-api/#list-configuration-packages-and-their-stages

list_stage_files(package_name: str, stage_name: str, suppress_exception: bool | None = None) → Any[source]

List packages and their stages.

Parameters:

package_name – Package names with the _ prefix are reserved for internal packages and must not be used. You can recognize _api, _etc and _cluster when querying specific objects and packages.
stage_name – The stage name, for example 7e7861c8-8008-4e8d-9910-2a0bb26921bd.
suppress_exception – If this parameter is set to True, no exceptions are thrown.

See:

Icinga2 API documentation: doc/12-icinga2-api/#list-configuration-package-stage-files

fetch_stage_file(package_name: str, stage_name: str, relpath: str, suppress_exception: bool | None = None) → str[source]

Fetch the content of a specific configuration file

Parameters:

package_name – Package names with the _ prefix are reserved for internal packages and must not be used. You can recognize _api, _etc and _cluster when querying specific objects and packages.
stage_name – The stage name, for example 7e7861c8-8008-4e8d-9910-2a0bb26921bd.
relpath – The relative path of the requested configuration file.
suppress_exception – If this parameter is set to True, no exceptions are thrown.

See:

Icinga2 API documentation: doc/12-icinga2-api/#fetch-configuration-package-stage-files

get_package_stage_errors(package_name: str, stage_name: str, suppress_exception: bool | None = None) → str[source]

Check for validation errors.

Parameters:

package_name – Package names with the _ prefix are reserved for internal packages and must not be used. You can recognize _api, _etc and _cluster when querying specific objects and packages.
stage_name – The stage name, for example 7e7861c8-8008-4e8d-9910-2a0bb26921bd.
suppress_exception – If this parameter is set to True, no exceptions are thrown.

See:

Icinga2 API documentation: doc/12-icinga2-api/#configuration-package-stage-errors

delete_stage(package_name: str, stage_name: str, suppress_exception: bool | None = None) → Any[source]

Send a delete request in order to purge a configuration stage.

Parameters:

name – Package names with the _ prefix are reserved for internal packages and must not be used. You can recognize _api, _etc and _cluster when querying specific objects and packages.
stage_name – The stage name, for example 7e7861c8-8008-4e8d-9910-2a0bb26921bd.
suppress_exception – If this parameter is set to True, no exceptions are thrown.

See:

Icinga2 API documentation: doc/12-icinga2-api/#deleting-configuration-package-stage

delete_package(package_name: str, suppress_exception: bool | None = None) → Any[source]

Delete the configuration package entirely.

Parameters:

name – Package names with the _ prefix are reserved for internal packages and must not be used. You can recognize _api, _etc and _cluster when querying specific objects and packages.
suppress_exception – If this parameter is set to True, no exceptions are thrown.

See:

Icinga2 API documentation: doc/12-icinga2-api/#deleting-configuration-package

class pretiac.raw_client.TypesUrlEndpoint(client: RawClient)[source]

Bases: RequestHandler

path_prefix: for example objects for localhost:5665/v1/objects

list(object_type: Literal['ApiUser', 'CheckCommand', 'Dependency', 'Endpoint', 'EventCommand', 'Host', 'HostGroup', 'Notification', 'NotificationCommand', 'ScheduledDowntime', 'Service', 'ServiceGroup', 'TimePeriod', 'User', 'UserGroup', 'Zone'] | Literal['Comment', 'Downtime'] | Literal['ApiListener', 'CheckerComponent', 'CompatLogger', 'ElasticsearchWriter', 'ExternalCommandListener', 'FileLogger', 'GelfWriter', 'GraphiteWriter', 'IcingaApplication', 'IcingaDB', 'IdoMySqlConnection', 'IdoPgsqlConnection', 'InfluxdbWriter', 'Influxdb2Writer', 'JournaldLogger', 'LiveStatusListener', 'NotificationComponent', 'OpenTsdbWriter', 'PerfdataWriter', 'SyslogLogger', 'WindowsEventLogLogger'] | None = None) → Any[source]

Retrieve the configuration object types.

Parameters:: object_type – The type of the object, for example Service, Host or User.
See:: Icinga2 API documentation: doc/12-icinga2-api/#types

class pretiac.raw_client.TemplatesUrlEndpoint(client: RawClient)[source]

Bases: RequestHandler

Connects to the URL endpoint templates of the Icinga2 API.

path_prefix: for example objects for localhost:5665/v1/objects

list(object_type: Literal['ApiUser', 'CheckCommand', 'Dependency', 'Endpoint', 'EventCommand', 'Host', 'HostGroup', 'Notification', 'NotificationCommand', 'ScheduledDowntime', 'Service', 'ServiceGroup', 'TimePeriod', 'User', 'UserGroup', 'Zone', 'Comment', 'Downtime', 'ApiListener', 'CheckerComponent', 'CompatLogger', 'ElasticsearchWriter', 'ExternalCommandListener', 'FileLogger', 'GelfWriter', 'GraphiteWriter', 'IcingaApplication', 'IcingaDB', 'IdoMySqlConnection', 'IdoPgsqlConnection', 'InfluxdbWriter', 'Influxdb2Writer', 'JournaldLogger', 'LiveStatusListener', 'NotificationComponent', 'OpenTsdbWriter', 'PerfdataWriter', 'SyslogLogger', 'WindowsEventLogLogger'], filter: str | None = None) → Any[source]

Request information about configuration templates.

Parameters:

object_type – The type of the object, for example Service, Host or User.
filter – The template object can be accessed in the filter using the tmpl variable. In the example "match("g*", tmpl.name)" the match function is used to check a wildcard string pattern against tmpl.name.

See:

Icinga2 API documentation: doc/12-icinga2-api/#querying-templates

class pretiac.raw_client.VariablesUrlEndpoint(client: RawClient)[source]

Bases: RequestHandler

path_prefix: for example objects for localhost:5665/v1/objects

list() → Any[source]

Request information about global variables.

See:: Icinga2 API documentation: doc/12-icinga2-api/#querying-variables

class pretiac.raw_client.ConsoleUrlEndpoint(client: RawClient)[source]

Bases: RequestHandler

path_prefix: for example objects for localhost:5665/v1/objects

class pretiac.raw_client.RawClient(config: Config)[source]

Bases: object

This raw client is a thin wrapper around the Icinga2 REST API.

You can use the client with either username/password combination or using certificates.

Example using username and password:

from pretiac.client import Client

client = Client("localhost", 5665, "username", "password")

Example using certificates:

client = Client(
    "localhost",
    5665,
    certificate="/etc/ssl/certs/myhostname.crt",
    key="/etc/ssl/keys/myhostname.key",
)

If your public and private are in the same file, just use the certificate parameter.

To verify the server certificate specify a ca file as ca_file parameter.

Example:

from pretiac.client import Client

client = Client(
    "https://icinga2:5665",
    certificate="/etc/ssl/certs/myhostname.crt",
    key="/etc/ssl/keys/myhostname.key",
    ca_file="/etc/ssl/certs/my_ca.crt",
)

url: str

version: str

objects: ObjectsUrlEndpoint: Connects to the URL endpoint objects of the Icinga2 API.

actions: ActionsUrlEndpoint: Connects to the URL endpoint actions of the Icinga2 API.

events: EventsUrlEndpoint: Connects to the URL endpoint events of the Icinga2 API.

status: StatusUrlEndpoint: Connects to the URL endpoint status of the Icinga2 API.

config: ConfigUrlEndpoint: Connects to the URL endpoint config of the Icinga2 API.

types: TypesUrlEndpoint: Connects to the URL endpoint types of the Icinga2 API.

templates: TemplatesUrlEndpoint: Connects to the URL endpoint templates of the Icinga2 API.

variables: VariablesUrlEndpoint: Connects to the URL endpoint types of the Icinga2 API.

console: ConsoleUrlEndpoint: Connects to the URL endpoint types of the Icinga2 API.

get_client_config() → Config[source]

pretiac.request_handler

Provides the base class RequestHandler that is inherited by the different endpoint classes, for example the class Events handles the v1/events endpoint, the class Objects handles the v1/objects entpoint and so on…

pretiac.request_handler.normalize_state(state: HostState | ServiceState | Literal[0, 1, 2, 3] | int | Any) → int[source]

class pretiac.request_handler.RequestHandler(client: RawClient)[source]

Bases: object

Handles the HTTP requests to the Icinga2 API.

api_version: str

path_prefix: str | None: for example objects for localhost:5665/v1/objects

raw_client: RawClient

property versioned_path_prefix: str

property config: Config

Submodules

pretiac (__init__.py)

pretiac.client

pretiac.config

pretiac.exceptions

pretiac.object_types

pretiac.raw_client

pretiac.request_handler

pretiac (`init.py`)