Access monarch. More...

Public Class Methods
object	new (void)

void	DESTROY (void)

Public Object Methods
boolean	set_debuglevel (string newlevel)

int	get_debuglevel (void)

void	debug (string msglevel, string message)

string	get_debugmessages (void)

string	get_errormessages (void)

string	dassmonarch_version (void)

vstring	dassmonarch_vstring (void)

string	monarch_version (void)

vstring	monarch_vstring (void)

string	nagios_version (void)

boolean	update_or_insert_obj (string table, string searchcolumn, string searchvalue, hashref valref)

boolean or hash	host_exists (string hostname)

boolean or hash	hostgroup_exists (string hostgroupname)

boolean or hash	service_exists (string servicename)

boolean or hash	servicegroup_exists (string servicegroupname)

boolean or hash	host_extinfo_template_exists (string templatename)

boolean or hash	service_extinfo_template_exists (string templatename)

boolean or hash	monarch_group_exists (string monarch_group)

int	get_host_template_id (string host_template)

int	get_service_template_id (string service_template)

int	get_hostprofileid (string hostprofilename)

int	get_serviceprofileid (string serviceprofilename)

int	get_serviceid (string servicename)

int	get_hostid (string hostname)

int	get_host_serviceid (string hostname, string servicename)

int	get_hostgroupid (string hostgroupname)

int	get_command_id (string commandname)

int	get_escalation_tree_id (string escalationtreename, string type)

int	get_extended_host_information_template_id (param extended_host_information_template)

string	get_host_template_name (int hosttemplate_id)

string	get_hostprofilename (int hostprofile_id)

string	get_serviceprofilename (int serviceprofile_id)

string	get_genericservicename (int servicename_id)

string	get_hostname (int host_id)

string	get_servicename (int service_id)

string	get_host_address (string hostname)

arrayref	get_hosts_with_address (string address)

array	get_hostlist (void)

arrayref or array	get_hostgroups_for_host (string hostname)

arrayref or array	get_hosts_in_hostgroup (string hostgroup)

arrayref or array	get_hostservice_list (string hostname)

arrayref or array	get_service_hostlist (string servicename)

arrayref or array	get_all_service_dependencies (void)

boolean or hash	search_service_by_prefix (string substring)

boolean	import_host (string hostname, string alias, string address, string profile_name, boolean update)

boolean	import_host_api (string hostname, string alias, string address, string profile_name, boolean update)

boolean	clone_host (string src_host, string dest_host, string dest_alias, string dest_address)

boolean	clone_service (string src_service, string dest_service)

int	clone_hostprofile (string source_hostprofile, string target_hostprofile)

boolean	delete_hostprofile (string hostprofilename)

int	clone_service_template (string source_servicetemplate, string target_servicetemplate)

DEPRECATED boolean	assign_host_profile (string hostname, string hostprofilename, boolean replace)

boolean	assign_and_apply_hostprofile_to_host (string hostname, string hostprofilename, boolean replace)

boolean	apply_hostprofile_to_host (string hostname, string hostprofilename, boolean replace)

DEPRECATED boolean	apply_hostprofile_service_profiles (string hostname, string hostprofilename, boolean replace)

boolean	assign_and_apply_hostprofile_serviceprofiles (string hostname, string hostprofilename, boolean replace)

int	create_serviceprofile (string serviceprofilename, string serviceprofile_description)

boolean	assign_service_to_serviceprofile (string servicename, string serviceprofilename, string apply, boolean replace)

arrayref or array	get_serviceprofile_services (string serviceprofilename)

boolean	assign_and_apply_serviceprofile_to_host (string hostname, string serviceprofilename, boolean replace)

arrayref or array	get_hosts_with_serviceprofile (string serviceprofilename)

boolean	remove_serviceprofile_from_host (string hostname, string serviceprofilename)

boolean	create_hostgroup (string hostgroupname, string alias)

boolean	assign_hostgroup (string hostname, string hostgroup)

boolean	remove_host_from_hostgroup (string hostname, string hostgroup)

boolean	create_servicegroup (string servicegroupname, string alias, string service_escalation, string notes)

boolean	assign_servicegroup (string host, string service, string servicegroup)

boolean	set_generic_service_command (string servicename, string commandname)

boolean	set_generic_service_commandline (string servicename, string commandline)

boolean	set_host_overrides_properties (string hostname, hashref propref)

boolean	set_service_overrides_properties (string hostname, string servicename, hashref propref)

boolean	set_host_service_notification_interval (string hostname, string servicename, int interval)

boolean	set_host_service_freshness_threshold (string hostname, string servicename, int threshold)

boolean	add_service (string hostname, string service)

boolean	remove_service (string hostname, string servicename)

boolean	apply_host_template (string hostname, string host_template)

boolean	apply_service_template (string servicename, string service_template)

boolean	create_extended_host_info_template (string template_name, string notes, string notes_url, string action_url, string icon_image, string icon_image_alt, string statusmap_image, string vrml_image)

boolean	apply_extended_host_information_template (string hostname, string extended_host_information_template)

int	create_contact (string contact_name, string contact_alias, string contact_email, string contact_template, string contact_pager)

int	create_contactgroup (string contactgroup_name, string contactgroup_alias)

boolean	delete_contact (string contact_name)

boolean	delete_contactgroup (string contactgroup_name)

int	get_contact_template_id (string contacttemplatename)

int	get_contact_id (string contact_name)

int	get_contactgroup_id (string contactgroup_name)

arrayref or array	get_contactgroup_contacts (string contactgroup_name)

string	get_contactgroup_name (int contactgroup_id)

arrayref or array	get_hostgroup_contactgroups (string hostgroup_name)

arrayref or array	get_service_contactgroups (string servicename)

boolean	assign_contact_to_contactgroup (string contact_name, string contactgroup_name)

boolean	assign_contactgroup_to_hostgroup (string contactgroup_name, string hostgroup_name)

boolean	assign_contactgroup_to_servicename (string contactgroup_name, string servicename)

boolean	remove_contactgroup_from_servicename (string contactgroup_name, string servicename)

boolean	apply_hostescalation_tree (string hostname, string escalation_tree)

boolean	apply_service_escalation_tree_to_host (string hostname, string escalation_tree)

boolean	apply_serviceescalation_tree_to_hostservice (string hostname, string servicename, string escalation_tree)

boolean	apply_serviceescalation_tree_to_all_hostservices (string hostname, string escalation_tree)

boolean	delete_host (string hostname)

boolean	delete_hosts (string searchstring)

boolean	delete_hostgroup_members (string hostgroupname)

boolean	delete_hostgroup (string hostgroupname)

boolean	delete_service (string servicename)

boolean	delete_services (string searchstring)

boolean	delete_host_ext_info_template (string templatename)

boolean	delete_host_ext_info_template_list (string templatename_prefix)

boolean	set_parents (string hostname, arrayref parents)

array	get_host_parent (string hostname)

boolean	enable_active_host_checks (string hostname)

boolean	enable_active_service_checks (string hostname, string servicename)

boolean	enable_obsess_host_checks (string hostname)

boolean	enable_obsess_service_checks (string hostname, string servicename)

boolean	enable_all_active_service_checks_on_host (string hostname)

boolean	enable_all_obsess_service_checks_on_host (string hostname)

boolean	enable_active_service_check_on_hostgroup (string hostgroup, string servicename)

boolean	enable_obsess_service_check_on_hostgroup (string hostgroup, string servicename)

boolean	enable_all_active_service_checks_on_hostgroup (string hostgroup)

boolean	enable_all_obsess_service_checks_on_hostgroup (string hostgroup)

boolean	disable_active_host_checks (string hostname)

boolean	disable_active_service_checks (string hostname, string servicename)

boolean	disable_obsess_host_checks (string hostname)

boolean	disable_obsess_service_checks (string hostname, string servicename)

boolean	disable_all_active_service_checks_on_host (string hostname)

boolean	disable_all_obsess_service_checks_on_host (string hostname)

boolean	disable_active_service_check_on_hostgroup (string hostgroup, string servicename)

boolean	disable_obsess_service_check_on_hostgroup (string hostgroup, string servicename)

boolean	disable_all_active_service_checks_on_hostgroup (string hostgroup)

boolean	disable_all_obsess_service_checks_on_hostgroup (string hostgroup)

boolean	enable_host_notifications (string hostname)

boolean	disable_host_notifications (string hostname)

boolean	enable_host_service_notifications (string hostname, string servicename)

boolean	disable_host_service_notifications (string hostname, string servicename)

boolean	enable_all_notifications_on_host (string hostname)

boolean	disable_all_notifications_on_host (string hostname)

boolean	enable_host_service_freshness_checks (string hostname, string servicename)

boolean	disable_host_service_freshness_checks (string hostname, string servicename)

DEPRECATED boolean	assign_monarch_group_host (string monarch_group, string hostname)

boolean	assign_monarch_group_hosts (string monarch_group, arrayref hosts)

boolean	assign_monarch_group_hostgroups (string monarch_group, arrayref hostgroups)

boolean	assign_monarch_group_subgroups (string monarch_group, arrayref subgroups)

arrayref	get_monarch_group_hosts (string monarch_group)

arrayref	get_monarch_group_hostgroups (string monarch_group)

hashref	get_monarch_group_orphans (void)

arrayref	get_monarch_group_subgroups (string monarch_group)

string	get_monarchgroup_location (string monarch_group)

boolean	remove_monarch_group_hosts (string monarch_group, arrayref hosts)

boolean	remove_monarch_group_hostgroups (string monarch_group, arrayref hostgroups)

boolean	remove_monarch_group_subgroups (string monarch_group, arrayref subgroups)

int	create_external (string external_name, string description, string type, string content)

boolean	rename_external (string old_external_name, string new_external_name)

boolean	delete_external (string external_name)

boolean	assign_external_to_hostprofile (string hostprofile_name, string external_name)

boolean	assign_external_to_service (string service_name, string external_name)

boolean	apply_external_to_host (string host_name, string external_name, boolean modified)

boolean	apply_external_to_hostservice (string host_name, string service_name, string external_name, boolean modified)

boolean	modify_external (string external_name, string description, string content)

boolean	modify_host_external (string host_name, string external_name, string content, boolean modified)

boolean	modify_hostservice_external (string host_name, string service_name, string external_name, string content, boolean modified)

boolean	remove_external_from_hostprofile (string hostprofile_name, string external_name)

boolean	remove_external_from_service (string service_name, string external_name)

boolean	remove_external_from_host (string host_name, string external_name)

boolean	remove_external_from_hostservice (string host_name, string service_name, string external_name)

hashref	get_external (string external_name)

int	get_externalid (string external_name)

string	get_externalname (int external_id)

hashref	get_host_external (string host_name, string external_name)

hashref	get_hostservice_external (string host_name, string service_name, string external_name)

arrayref	list_externals (string type)

arrayref	list_hostprofile_externals (string hostprofile_name)

arrayref	list_service_externals (string service_name)

arrayref	list_host_externals (string host_name)

arrayref	list_hostservice_externals (string host_name, string service_name)

arrayref	list_hostprofiles_with_external (string external_name)

arrayref	list_services_with_external (string external_name)

arrayref	list_hosts_with_external (string external_name)

arrayref	list_hostservices_with_external (string external_name)

boolean	propagate_external (string external_name, boolean replace)

boolean	buildAllExternals (boolean force)

boolean	buildSomeExternals (arrayref hostsref, boolean force)

boolean	pre_flight_check (string monarch_group)

boolean	generateAndCommit (string annotation, boolean lock)

boolean	build_instance (string monarch_group)

Detailed Description

Access monarch.

This class provides methods to access the monarch database to automatically import and manage configuration data. A fair number of these routines can be called in either scalar or list context. In such cases, the method prototype lists only the most common usage. The description of the method return value gives more detail on how the returned data changes with the calling context.

Also note that database errors may occur at any time, for reasons unrelated to this package. A calling application must be aware of that possibility, and be able to recognize when intended operations have not completed as planned. To that end, most routines in this package will return undef (in scalar context) or an empty list (in list context) when a database error occurs. An undef in scalar context is sufficiently distinctive that it usually signals unambiguously that a failure has occurred. An empty list might or might not be sufficiently distinctive to conclude that a failure has occurred; that depends on the nature of the method being called. Application code must be written to be vigilant about testing returned values and responding accordingly.

Member Function Documentation

boolean dassmonarch::add_service	(	string	hostname,
		string	service
	)

Add a generic service to a host, thereby creating a host service.

Parameters

hostname	name of the host to which the service will be added
service	name of the service to add to the host

Returns: status: true if successful, false otherwise

boolean dassmonarch::apply_extended_host_information_template	(	string	hostname,
		string	extended_host_information_template
	)

Apply an extended host information template to a host.

Parameters

hostname	name of the host to apply the template to
extended_host_information_template	name of the template to apply

Returns: status: true if successful, else false

boolean dassmonarch::apply_external_to_host	(	string	host_name,
		string	external_name,
		boolean	modified
	)

Apply a host external to a host. Overwrite existing external content and metadata if this host external was already applied.

Parameters

host_name	Name of the host to which the external is to be applied.
external_name	Name of the host external to be applied.
modified	True, if the external is to be marked as a custom copy. False, if the external is to be marked as an unmodified copy.

Returns: status: true if successful, false otherwise

boolean dassmonarch::apply_external_to_hostservice	(	string	host_name,
		string	service_name,
		string	external_name,
		boolean	modified
	)

Apply a service external to a host service. Overwrite existing external content and metadata if this service external was already applied.

Parameters

host_name	Name of the host on which the service resides.
service_name	Name of the host service to which the external is to be applied.
external_name	Name of the host external to be applied.
modified	True, if the external is to be marked as a custom copy. False, if the external is to be marked as an unmodified copy.

Returns: status: true if successful, false otherwise

boolean dassmonarch::apply_host_template	(	string	hostname,
		string	host_template
	)

Apply a host_template to a host.

Parameters

hostname	name of the host to which the host template should be applied
host_template	name of the host template to apply

Returns: status: true if successful, else false

boolean dassmonarch::apply_hostescalation_tree	(	string	hostname,
		string	escalation_tree
	)

Apply a host escalation tree to a host.

Parameters

hostname	name of the host to which the escalation tree should be applied
escalation_tree	name of the host escalation tree to apply to the host

Returns: status: true if successful, else false

DEPRECATED boolean dassmonarch::apply_hostprofile_service_profiles	(	string	hostname,
		string	hostprofilename,
		boolean	replace
	)

Apply all service profiles which are assigned to a host profile to a host. This function is deprecated, due to a misleading name; use assign_and_apply_hostprofile_serviceprofiles() instead.

Parameters

hostname	name of the host to which the serviceprofiles should be applied
hostprofilename	name of the hostprofile whose serviceprofiles will be assigned to the host
replace	True, if existing services should be replaced by services in the host profile's service profiles. False, if services should be merged.

Returns: status: true if successful, false otherwise

boolean dassmonarch::apply_hostprofile_to_host	(	string	hostname,
		string	hostprofilename,
		boolean	replace
	)

Apply a host profile and associated service profiles to a host. This routine is similar to assign_and_apply_hostprofile_to_host(), but it does not permanently assign the host profile to the host. (That said, service profiles associated with the host profile are still assigned to the host before they are applied.) This routine is provided to support the case where a host is being added to the system and its association with the host profile is to be indirect through a hostgroup that is assigned to be managed by the host profile, instead of having the host profile be directly assigned to the host.

Parameters

hostname	name of the host to which the hostprofile should be applied
hostprofilename	name of the hostprofile to apply to the host
replace	True, if existing services should be replaced by services in associated service profiles. False, if services should be merged.

Returns: status: true if successful, false otherwise

boolean dassmonarch::apply_service_escalation_tree_to_host	(	string	hostname,
		string	escalation_tree
	)

Apply a service escalation tree to a host. This overwrites existing service escalations for any particular service of that host. This means you can only use this option if ALL services on the host are to be escalated following the same tree.

Parameters

hostname	name of the host to which the escalation tree should be applied
escalation_tree	name of the service escalation tree to apply

Returns: status: true if successful, false otherwise

boolean dassmonarch::apply_service_template	(	string	servicename,
		string	service_template
	)

Apply a service_template to a service.

Parameters

servicename	name of the generic service to which the service template should be applied
service_template	name of the service template to apply

Returns: status: true if successful, else false

boolean dassmonarch::apply_serviceescalation_tree_to_all_hostservices	(	string	hostname,
		string	escalation_tree
	)

Apply a service escalation tree to all already-defined services on a host. Use this, if you want to have different escalation trees for later defined services. If you want to have the same tree on definitely all services on a host, use apply_service_escalation_tree_to_host() instead.

Parameters

hostname	name of the host on which services to which the escalation tree should be applied reside
escalation_tree	name of the service escalation tree to apply

Returns: status: true if successful, else false

boolean dassmonarch::apply_serviceescalation_tree_to_hostservice	(	string	hostname,
		string	servicename,
		string	escalation_tree
	)

Apply a service escalation tree to a particular service on a host.

Parameters

hostname	name of the host on which the service to which the escalation tree should be applied resides
servicename	name of the service to which the escalation tree should be applied
escalation_tree	name of the service escalation tree to apply

Returns: status: true if successful, else false

boolean dassmonarch::assign_and_apply_hostprofile_serviceprofiles	(	string	hostname,
		string	hostprofilename,
		boolean	replace
	)

Apply all service profiles which are assigned to a host profile to a host.

Parameters

hostname	name of the host to which the serviceprofiles should be applied
hostprofilename	name of the hostprofile whose serviceprofiles will be assigned to the host
replace	True, if existing services should be replaced by services in the host profile's service profiles. False, if services should be merged.

Returns: status: true if successful, false otherwise

boolean dassmonarch::assign_and_apply_hostprofile_to_host	(	string	hostname,
		string	hostprofilename,
		boolean	replace
	)

Assign and apply a host profile and associated service profiles to a host.

Parameters

hostname	name of the host to which the hostprofile should be applied
hostprofilename	name of the hostprofile to assign and apply to the host
replace	True, if existing services should be replaced by services in associated service profiles. False, if services should be merged.

Returns: status: true if successful, false otherwise

boolean dassmonarch::assign_and_apply_serviceprofile_to_host	(	string	hostname,
		string	serviceprofilename,
		boolean	replace
	)

Assign a service profile to a host, and apply the corresponding services to that host.

Parameters

hostname	name of the host to which the serviceprofile is to be assigned and applied
serviceprofilename	name of the serviceprofile to assign and apply to the host
replace	True, if existing services should be replaced by services in the service profile. False, if services should be merged.

Returns: status: true if successful, false otherwise

boolean dassmonarch::assign_contact_to_contactgroup	(	string	contact_name,
		string	contactgroup_name
	)

Assign a contact to a contactgroup.

Parameters

contact_name	name of the the contact to assign
contactgroup_name	name of the contactgroup to which the contact should be assigned

Returns: status: true, if operation was successful; false otherwise

boolean dassmonarch::assign_contactgroup_to_hostgroup	(	string	contactgroup_name,
		string	hostgroup_name
	)

Assign a contactgroup to a hostgroup.

Parameters

contactgroup_name	name of the contactgroup to assign
hostgroup_name	name of the hostgroup to which the contactgroup should be assigned

Returns: status: true, if operation was successful; false otherwise

boolean dassmonarch::assign_contactgroup_to_servicename	(	string	contactgroup_name,
		string	servicename
	)

Assign a contactgroup to a servicename.

Parameters

contactgroup_name	name of the contactgroup to assign
servicename	name of the generic service to which the contactgroup should be assigned

Returns: status: true, if operation was successful; false otherwise

boolean dassmonarch::assign_external_to_hostprofile	(	string	hostprofile_name,
		string	external_name
	)

Assign a host external to a host profile.

Parameters

hostprofile_name	Name of the host profile.
external_name	Name of the host external.

Returns: status: true if successful, false otherwise

boolean dassmonarch::assign_external_to_service	(	string	service_name,
		string	external_name
	)

Assign a service external to a generic service.

Parameters

service_name	Name of the service.
external_name	Name of the service external.

Returns: status: true if successful, false otherwise

DEPRECATED boolean dassmonarch::assign_host_profile	(	string	hostname,
		string	hostprofilename,
		boolean	replace
	)

Assign a host profile and associated service profiles to a host. This function is deprecated, due to a misleading name; use assign_and_apply_hostprofile_to_host() instead.

Parameters

hostname	name of the host to which the hostprofile should be applied
hostprofilename	name of the hostprofile to assign and apply to the host
replace	True, if existing services should be replaced by services in associated service profiles. False, if services should be merged.

Returns: status: true if successful, false otherwise

boolean dassmonarch::assign_hostgroup	(	string	hostname,
		string	hostgroup
	)

Assign a host to a hostgroup.

Parameters

hostname	name of the host to be assigned to the hostgroup
hostgroup	name of the hostgroup the host shall join

Returns: status: true if operation successful, else false

DEPRECATED boolean dassmonarch::assign_monarch_group_host	(	string	monarch_group,
		string	hostname
	)

Assign a single host to a Monarch Group. This function is deprecated; use assign_monarch_group_hosts() instead.

Parameters

monarch_group	name of a Monarch Group
hostname	name of a particular single host

Returns: status: true if assign_monarch_group_host succeeds, false otherwise.

boolean dassmonarch::assign_monarch_group_hostgroups	(	string	monarch_group,
		arrayref	hostgroups
	)

Assign specified hostgroups to a Monarch Group.

Parameters

monarch_group	name of the Monarch Group to which hostgroups should be assigned
hostgroups	reference to an array of hostgroup names to be assigned to the Monarch Group

Returns: status: true if assign_monarch_group_hostgroups completely succeeds, false otherwise.

boolean dassmonarch::assign_monarch_group_hosts	(	string	monarch_group,
		arrayref	hosts
	)

Assign specified hosts to a Monarch Group.

Parameters

monarch_group	name of the Monarch Group to which hosts should be directly assigned
hosts	reference to an array of hostnames to be assigned to the Monarch Group

Returns: status: true if assign_monarch_group_hosts completely succeeds, false otherwise.

boolean dassmonarch::assign_monarch_group_subgroups	(	string	monarch_group,
		arrayref	subgroups
	)

Assign specified subgroups to a Monarch Group.

Parameters

monarch_group	name of the Monarch Group to which subgroups should be assigned
subgroups	reference to an array of Monarch Group names to be assigned as subgroups of the Monarch Group

Returns: status: true if assign_monarch_group_subgroups completely succeeds, false otherwise.

boolean dassmonarch::assign_service_to_serviceprofile	(	string	servicename,
		string	serviceprofilename,
		string	apply,
		boolean	replace
	)

Assign a service to a serviceprofile, and apply that serviceprofile to all hosts to which it is already assigned.

Parameters

servicename	name of the generic service to assign to the serviceprofile
serviceprofilename	name of the serviceprofile to which the service should be assigned, and which may be re-applied to all hosts to which this serviceprofile is already assigned, depending on the setting of the apply parameter
apply	false (default, if not provided), if the serviceprofile should not be apply to any hosts; 'apply-if-new', if the serviceprofile should be applied to existing hosts that already have the serviceprofile assigned, but only if the named service was not already part of the serviceprofile; 'apply', if the serviceprofile should be applied to existing hosts that already have the serviceprofile assigned, whether or not the named service was already part of the serviceprofile
replace	Boolean flag. True, if (when applying the service profile to hosts) all existing services on hosts that already have the named serviceprofile assigned should be replaced by just the services in the one specified serviceprofile. False (default, if not provided) if services from the serviceprofile should be merged into those already attached to such hosts.

Returns: status: true, if operation was successful; otherwise, false (0) if a logical error occurred (e.g., the named serviceprofile does not exist), undef if a database error occurred

boolean dassmonarch::assign_servicegroup	(	string	host,
		string	service,
		string	servicegroup
	)

Assign a specific host's service to a servicegroup.

Parameters

host	name of the host on which the service to be included in the servicegroup resides
service	name of the host's service
servicegroup	name of the servicegroup which the host service will now be a member of

Returns: status: true if successful (if service is already a group member, too); false otherwise

boolean dassmonarch::build_instance ( string monarch_group )

Build the configuration for a given Monarch Group, in the directory configured in the group's details, and call the Monarch Deploy code to push the updated configuration to the child server.

Parameters

monarch_group name of the Monarch Group to build

Returns: status: true if build and deploy succeeds, false otherwise.

boolean dassmonarch::buildAllExternals ( boolean force )

Build externals for all hosts.

Parameters

force boolean flag; true means force regeneration even if there is no significant change in content

Returns: status: true if build_all_externals succeeds, false otherwise.

boolean dassmonarch::buildSomeExternals	(	arrayref	hostsref,
		boolean	force
	)

Build externals for a set of hosts.

Parameters

hostsref	reference to an array of hostnames, to build externals only for particular hosts; undefined, to build externals for all hosts
force	boolean flag; true means force regeneration even if there is no significant change in content

Returns: status: true if build_some_externals succeeds, false otherwise.

boolean dassmonarch::clone_host	(	string	src_host,
		string	dest_host,
		string	dest_alias,
		string	dest_address
	)

Clone a host.

Parameters

src_host	name of the host to be cloned
dest_host	name of the resulting host
dest_alias	alias for the resulting host
dest_address	address of the resulting host

Returns: status: true if successful, false otherwise

int dassmonarch::clone_hostprofile	(	string	source_hostprofile,
		string	target_hostprofile
	)

Clone a hostprofile.

Parameters

source_hostprofile	name of the hostprofile to clone
target_hostprofile	name of the new cloned hostprofile

Returns: hostprofile_id: > 0 if cloning was successful; otherwise, 0 if logical problems were found, undef if a database error occurred

boolean dassmonarch::clone_service	(	string	src_service,
		string	dest_service
	)

Clone a generic service.

Parameters

src_service	name of the service to be cloned
dest_service	name of the resulting service

Returns: status: true if successful, false otherwise

int dassmonarch::clone_service_template	(	string	source_servicetemplate,
		string	target_servicetemplate
	)

Clone a servicetemplate.

Parameters

source_servicetemplate	name of the servicetemplate to clone
target_servicetemplate	name of the new cloned servicetemplate

Returns: servicetemplate_id: > 0 if cloning was successful; otherwise, 0 if logical problems found, undef if a database error occurred

int dassmonarch::create_contact	(	string	contact_name,
		string	contact_alias,
		string	contact_email,
		string	contact_template,
		string	contact_pager
	)

Create a contact using a template.

Parameters

contact_name	name of the new contact
contact_alias	alias for the new contact
contact_email	the new contact's email address
contact_template	name of the contact template to assign to the new contact
contact_pager	the new contact's pager number

Returns: contact_id: > 0, if a contact was created; otherwise, 0 if a logical error occurred (e.g., the name already exists), undef if a database error occurred

int dassmonarch::create_contactgroup	(	string	contactgroup_name,
		string	contactgroup_alias
	)

Create an empty contactgroup.

Parameters

contactgroup_name	name of the new contactgroup
contactgroup_alias	alias for the new contactgroup

Returns: contactgroup_id: > 0, if a contactgroup was created; otherwise, 0 if a logical error occurred (e.g., the name already exists), undef if a database error occurred

boolean dassmonarch::create_extended_host_info_template	(	string	template_name,
		string	notes,
		string	notes_url,
		string	action_url,
		string	icon_image,
		string	icon_image_alt,
		string	statusmap_image,
		string	vrml_image
	)

Create an extended host info template. Use empty strings, if particular fields should not be defined.

Parameters

template_name	name for the new extended host info template
notes	additional notes
notes_url	URL for additional notes
action_url	URL for action to display
icon_image	icon filename for this extended host info template
icon_image_alt	alternative text for icon
statusmap_image	filename for the icon to be displayed on the Nagios status map
vrml_image	icon filename for 3D VRML map

Returns: status: true if successful, false otherwise

int dassmonarch::create_external	(	string	external_name,
		string	description,
		string	type,
		string	content
	)

Create a new free external.

Parameters

external_name	Name of the external.
description	Brief comment about the external.
type	Type of the external ("host" or "service").
content	Content of the external.

Returns: external_id: > 0, if definition was successful; 0 otherwise

boolean dassmonarch::create_hostgroup	(	string	hostgroupname,
		string	alias
	)

Create a new hostgroup.

Parameters

hostgroupname	name for the new hostgroup
alias	alias for the new hostgroup

Returns: status: true if successful, false otherwise

boolean dassmonarch::create_servicegroup	(	string	servicegroupname,
		string	alias,
		string	service_escalation,
		string	notes
	)

Create a new servicegroup.

Parameters

servicegroupname	name of the new servicegroup
alias	alias for the new servicegroup
service_escalation	(optional) name of the service escalation tree for the new servicegroup
notes	(optional) notes about the new servicegroup

Returns: status: true if successful, false otherwise

int dassmonarch::create_serviceprofile	(	string	serviceprofilename,
		string	serviceprofile_description
	)

Create an empty serviceprofile.

Parameters

serviceprofilename	name of the new profile
serviceprofile_description	short text description of the new profile

Returns: serviceprofile_id: > 0, if a serviceprofile was created; otherwise, 0 if a logical error occurred (e.g., the name already exists), undef if a database error occurred

string dassmonarch::dassmonarch_version ( void )

Get the dassmonarch version found by the constructor.

Returns: Full dassmonarch version as a string.

vstring dassmonarch::dassmonarch_vstring ( void )

Get the dassmonarch version Perl vstring manufactured by the constructor.

Returns: dassmonarch version as a Perl vstring.

void dassmonarch::debug	(	string	msglevel,
		string	message
	)

Print a debug message to stderr, if it reaches current debuglevel.

Parameters

msglevel	one of 'error', 'warning', 'info', or 'verbose'
message	the debug message; will be printed out if msglevel is above the general debuglevel

Returns: nothing

boolean dassmonarch::delete_contact ( string contact_name )

Delete a contact from the monarch database.

Parameters

contact_name name of the contact to be deleted

Returns: status: true if successful; false if the specified contact does not exist or if a database operation has failed.

boolean dassmonarch::delete_contactgroup ( string contactgroup_name )

Delete a contactgroup from the monarch database.

Parameters

contactgroup_name name of the contactgroup to be deleted

Returns: status: true if successful; false if the specified contactgroup does not exist or if a database operation has failed.

boolean dassmonarch::delete_external ( string external_name )

Delete a free external and all associated applied externals.

Parameters

external_name Name of the external to delete.

Returns: status: true if successful, false otherwise

boolean dassmonarch::delete_host ( string hostname )

Delete a host from the monarch database.

Parameters

hostname name of the host to be deleted

Returns: status: true if successful; false if the specified host does not exist or if a database operation has failed

boolean dassmonarch::delete_host_ext_info_template ( string templatename )

Delete a host extended info template from the monarch database.

Parameters

templatename name of the host extended info template to be deleted

Returns: status: true if successful, false otherwise

boolean dassmonarch::delete_host_ext_info_template_list ( string templatename_prefix )

Delete from the monarch database all host extended info templates whose name begins with a given prefix.

Parameters

templatename_prefix host extended info template name prefix to search for

Returns: status: true if successful, false otherwise

boolean dassmonarch::delete_hostgroup ( string hostgroupname )

Delete a hostgroup from the monarch database.

Parameters

hostgroupname name of the hostgroup to be deleted

Returns: status: true if successful; false if the specified hostgroup does not exist or if a database operation has failed

boolean dassmonarch::delete_hostgroup_members ( string hostgroupname )

Delete all the members (hosts) from a hostgroup. Use of this routine is strongly recommended instead of deleting and re-creating the hostgroup itself if you just need to change its membership.

Parameters

hostgroupname name of the hostgroup from which all member hosts are to be deleted

Returns: status: true if successful; false if the specified hostgroup does not exist or if a database operation has failed.

boolean dassmonarch::delete_hostprofile ( string hostprofilename )

Delete a hostprofile from the monarch database.

Parameters

hostprofilename name of the hostprofile to be deleted

Returns: status: true if successful; false if the specified hostprofile does not exist or if a database operation has failed.

boolean dassmonarch::delete_hosts ( string searchstring )

Delete a bunch of hosts.

Parameters

searchstring all hosts whose names include this substring will be deleted

Returns: status: true if successful; false if no hosts with searchstring are found or if one delete action fails

boolean dassmonarch::delete_service ( string servicename )

Delete a generic service from the monarch database, along with all of the host services with the same name.

Parameters

servicename name of the generic service to be deleted

Returns: status: true if successful, false otherwise

boolean dassmonarch::delete_services ( string searchstring )

Delete a bunch of generic services, and along with them, all the host services with the same servicenames.

Parameters

searchstring all generic services whose names include this substring will be deleted

Returns: status: true if successful; false if no services with searchstring are found or if delete action fails

void dassmonarch::DESTROY ( void )

Destructor, closes database connection to monarch. Will be called automatically by interpreter, when object goes out of scope or program ends.

boolean dassmonarch::disable_active_host_checks ( string hostname )

Disable active hostchecks for a particular host.

Parameters

hostname name of the host to deactivate hostchecks for

Returns: status: true if successful, false otherwise

boolean dassmonarch::disable_active_service_check_on_hostgroup	(	string	hostgroup,
		string	servicename
	)

Disable active checks for a particular service check on all hosts of a given hostgroup.

Parameters

hostgroup	name of the hostgroup containing the hosts on which the named service may reside
servicename	name of the service on those hosts whose active service checks should be disabled

Returns: status: true if successful, false if one of the operations fails. Will be also false if the service does not exist for one of the hosts in hostgroup.

boolean dassmonarch::disable_active_service_checks	(	string	hostname,
		string	servicename
	)

Disable Checks for a particular service on a dedicated host.

Parameters

hostname	name of the host on which the the service resides
servicename	name of the service whose active checks are to be disabled

Returns: status: true if successful, false otherwise

boolean dassmonarch::disable_all_active_service_checks_on_host ( string hostname )

Disable all active service checks on a host.

Parameters

hostname name of the host whose active service checks should be disabled

Returns: status: true if operation successful for all services on host, false otherwise

boolean dassmonarch::disable_all_active_service_checks_on_hostgroup ( string hostgroup )

Disable active checks for all service check on all hosts of a given hostgroup.

Parameters

hostgroup name of the hostgroup containing the hosts on which all active service checks should be disabled

Returns: status: true if successful, false if one of the operations fails. Will be also false if the service does not exist for one of the hosts in hostgroup.

boolean dassmonarch::disable_all_notifications_on_host ( string hostname )

Disable all host-check and service-check notifications on a specified host.

Parameters

hostname name of the host on which notifications are to be disabled

Returns: status: true if the operation was successful for the host check and all service checks on the host, false otherwise

boolean dassmonarch::disable_all_obsess_service_checks_on_host ( string hostname )

Disable obsessing for all service checks on a host.

Parameters

hostname name of the host whose service checks should not be obsessed over

Returns: status: true if successful, false otherwise

boolean dassmonarch::disable_all_obsess_service_checks_on_hostgroup ( string hostgroup )

Disable obsessing for all service checks on all hosts in a hostgroup.

Parameters

hostgroup name of the hostgroup containing the hosts on which service checks should not be obsessed over

Returns: status: true if successful, false otherwise

boolean dassmonarch::disable_host_notifications ( string hostname )

Disable notification for host checks for a particular host.

Parameters

hostname name of the host for which notifications should be disabled

Returns: status: true if successful, false otherwise

boolean dassmonarch::disable_host_service_freshness_checks	(	string	hostname,
		string	servicename
	)

Disable Checks for a particular service on a dedicated host.

Parameters

hostname	name of the host on which the service resides
servicename	name of the service for which freshness checks should be disabled

Returns: status: true if successful, false otherwise

boolean dassmonarch::disable_host_service_notifications	(	string	hostname,
		string	servicename
	)

Disable notifications for a particular service on a dedicated host.

Parameters

hostname	name of the host on which the service resides
servicename	name of the service for which notifications should be disabled

Returns: status: true if successful, false otherwise

boolean dassmonarch::disable_obsess_host_checks ( string hostname )

Disable obsessing of host checks for a particular host.

Parameters

hostname name of the host for which obsessing should be deactivated

Returns: status: true if successful, false otherwise

boolean dassmonarch::disable_obsess_service_check_on_hostgroup	(	string	hostgroup,
		string	servicename
	)

Disable obsessing for a particular service check on all hosts of a given hostgroup.

Parameters

hostgroup	name of the hostgroup containing the hosts on which the named service may reside
servicename	name of the service on those hosts whose service checks should not be obsessed over

Returns: status: true if successful, false if one of the operations fails. Will be also false if the service does not exist for one of the hosts in hostgroup.

boolean dassmonarch::disable_obsess_service_checks	(	string	hostname,
		string	servicename
	)

Disable obsessing for a particular service check.

Parameters

hostname	name of the host on which the the service resides
servicename	name of the service whose service checks should not be obsessed over

Returns: status: true if successful, false otherwise

boolean dassmonarch::enable_active_host_checks ( string hostname )

Activate host checks.

Parameters

hostname name of the host to activate hostchecks for

Returns: status: true if successful, false otherwise

boolean dassmonarch::enable_active_service_check_on_hostgroup	(	string	hostgroup,
		string	servicename
	)

Enable active checks for a particular service check on all hosts of a given hostgroup.

Parameters

hostgroup	name of the hostgroup containing the hosts on which the named service may reside
servicename	name of the service on those hosts whose active service checks should be enabled

Returns: status: true if successful, false otherwise

boolean dassmonarch::enable_active_service_checks	(	string	hostname,
		string	servicename
	)

Activate checks for a dedicated service on a particular host.

Parameters

hostname	name of the host on which the the service resides
servicename	name of the service whose active checks are to be enabled

Returns: status: true if successful, false otherwise

boolean dassmonarch::enable_all_active_service_checks_on_host ( string hostname )

Enable all active service checks on a given host.

Parameters

hostname name of the host whose active service checks should be enabled

Returns: status: true if all operations are successful, false otherwise

boolean dassmonarch::enable_all_active_service_checks_on_hostgroup ( string hostgroup )

Enable active checks for all services on all hosts of a given hostgroup.

Parameters

hostgroup name of the hostgroup containing the hosts on which all active service checks should be enabled

Returns: status: true if successful, false otherwise

boolean dassmonarch::enable_all_notifications_on_host ( string hostname )

Enable all host-check and service-check notifications on a specified host.

Parameters

hostname name of the host on which notifications are to be enabled

Returns: status: true if the operation was successful for the host check and all service checks on the host, false otherwise

boolean dassmonarch::enable_all_obsess_service_checks_on_host ( string hostname )

Enable obsessing for all service checks on a host.

Parameters

hostname name of the host whose service checks should be obsessed over

Returns: status: true if successful, false otherwise

boolean dassmonarch::enable_all_obsess_service_checks_on_hostgroup ( string hostgroup )

Enable obsessing for all service checks on all hosts in a hostgroup.

Parameters

hostgroup name of the hostgroup containing the hosts on which service checks should be obsessed over

Returns: status: true if successful, false otherwise

boolean dassmonarch::enable_host_notifications ( string hostname )

Disable notification for host checks for a particular host.

Parameters

hostname name of the host for which notifications should be enabled

Returns: status: true if successful, false otherwise

boolean dassmonarch::enable_host_service_freshness_checks	(	string	hostname,
		string	servicename
	)

Activate checks for a dedicated service on a particular host.

Parameters

hostname	name of the host on which the service resides
servicename	name of the service for which freshness checks should be enabled

Returns: status: true if successful, false otherwise

boolean dassmonarch::enable_host_service_notifications	(	string	hostname,
		string	servicename
	)

Disable notifications for a particular service on a dedicated host.

Parameters

hostname	name of the host on which the service resides
servicename	name of the service for which notifications should be enabled

Returns: status: true if successful, false otherwise

boolean dassmonarch::enable_obsess_host_checks ( string hostname )

Enable obsessing of host checks for a particular host.

Parameters

hostname name of the host for which obsessing should be activated

Returns: status: true if successful, false otherwise

boolean dassmonarch::enable_obsess_service_check_on_hostgroup	(	string	hostgroup,
		string	servicename
	)

Enable obsessing for a particular service check on all hosts of a given hostgroup.

Parameters

hostgroup	name of the hostgroup containing the hosts on which the named service may reside
servicename	name of the service on those hosts whose service checks should be obsessed over

Returns: status: true if successful, false otherwise

boolean dassmonarch::enable_obsess_service_checks	(	string	hostname,
		string	servicename
	)

Enable obsessing for a particular service check.

Parameters

hostname	name of the host on which the the service resides
servicename	name of the service whose service checks should be obsessed over

Returns: status: true if successful, false otherwise

boolean dassmonarch::generateAndCommit	(	string	annotation,
		boolean	lock
	)

Perform a pre-flight check, do a commit, and create a backup if the Nagios part of the commit succeeds.

Parameters

annotation	notes on what is motivating this Commit; used to describe the associated automatic backup
lock	boolean flag; true means make the automatic backup immune from automated deletion

Returns: status: true if commit succeeds, false otherwise.

arrayref or array dassmonarch::get_all_service_dependencies ( void )

Get all service dependencies as a hash.

Returns: service_dependencies: in list context, an array of quadruples. Each quadruple consists of hostname, servicename, depending host, depending service. IN scalar context, an arrayref for the quadrupples.

int dassmonarch::get_command_id ( string commandname )

Find the command_id for a named command.

Parameters

commandname name of the command to search for

Returns: command_id: > 0 if the command exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

int dassmonarch::get_contact_id ( string contact_name )

Find the contact_id for a named contact.

Parameters

contact_name name of the contact to search for

Returns: contact_id from table contacts, > 0 if the contact exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

int dassmonarch::get_contact_template_id ( string contacttemplatename )

Find the contacttemplate_id for a named contact template.

Parameters

contacttemplatename name of the contact template to search for

Returns: contacttemplate_id from table contact_templates, > 0 if the contact template exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

arrayref or array dassmonarch::get_contactgroup_contacts ( string contactgroup_name )

Get a list of the contacts assigned to a certain contactgroup.

Parameters

contactgroup_name name of the contactgroup to search for

Returns: contactnames: In list context, a list of contact names, or an empty list of the contactgroup does not exist, it has no associated contacts, or an error occurs (the latter case being indistinguishable from the logical conditions that can generate an empty list, so this mode of calling is not robust). In scalar context, an arrayref for the list of contact names (which will be legitimately empty if the contactgroup does not exist or it has no associated contactgroups), or undef if an error occurs, which makes it easy to distinguish an error condition.

int dassmonarch::get_contactgroup_id ( string contactgroup_name )

Find the contactgroup_id for a named contactgroup.

Parameters

contactgroup_name name of the contactgroup to search for

Returns: contactgroup_id from table contactgroups, > 0 if the contact group exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

string dassmonarch::get_contactgroup_name ( int contactgroup_id )

Get the contactgroup name for a given ID.

Parameters

contactgroup_id ID of the contactgroup to search for

Returns: contactgroup_name: the found contactgroup name if the contact group exists; otherwise, an empty string if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

int dassmonarch::get_debuglevel ( void )

Get the dassmonarch logging debug level as an integer.

Returns: debuglevel: the current logging level of the dassmonarch package

string dassmonarch::get_debugmessages ( void )

Get all debug messages generated since instantiation.

Returns: debugmsg containing all debug messages

string dassmonarch::get_errormessages ( void )

Get all error messages generated since instantiation.

Returns: errormsg containing all error messages

int dassmonarch::get_escalation_tree_id	(	string	escalationtreename,
		string	type
	)

Find the escalation tree ID of a given escalation tree name.

Parameters

escalationtreename	name of the escalation tree to search for
type	escalation type to search for, one of 'host' or 'service'

Returns: tree_id from table escalation_trees, > 0 if the named escalation tree exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

int dassmonarch::get_extended_host_information_template_id ( param extended_host_information_template )

Find the database ID of a given extended host information template.

Parameters

extended_host_information_template name of the extended host info template to search for

Returns: hostextinfo_id from table extended_host_info_templates, > 0 if the extended host info template exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

hashref dassmonarch::get_external ( string external_name )

Find details of a free external, given an external name.

Parameters

external_name Name of the external to search for.

Returns: hashref pointing to details if external exists; false otherwise (reference to empty hash if external does not exist, undefined if search failed)

int dassmonarch::get_externalid ( string external_name )

Find external ID, given an external name.

Parameters

external_name Name of the external to search for.

Returns: external_id: > 0 if external exists; false otherwise (0 if external does not exist, undefined if search failed)

string dassmonarch::get_externalname ( int external_id )

Find external name, given an external ID.

Parameters

external_id ID of the external to search for.

Returns: name of external if external exists; otherwise, undefined

string dassmonarch::get_genericservicename ( int servicename_id )

Get the service name for a given generic service name ID.

Parameters

servicename_id ID of the generic service to search for

Returns: service_name: the found servicename; otherwise, undefined (false).

string dassmonarch::get_host_address ( string hostname )

Find the address of a given host.

Parameters

hostname name of the host to search for

Returns: address: the found host address if the host exists; otherwise, an empty string if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

hashref dassmonarch::get_host_external	(	string	host_name,
		string	external_name
	)

Find details of an applied host external.

Parameters

host_name	Name of the host to which the external was applied.
external_name	Name of the external to search for.

Returns: hashref pointing to details, if external exists; reference to empty hash, if the applied host external does not exist; undefined, if search failed

array dassmonarch::get_host_parent ( string hostname )

Get parents, if any, of a named host.

Parameters

hostname name of the host whose parents to deliver

Returns: parent_names false otherwise

int dassmonarch::get_host_serviceid	(	string	hostname,
		string	servicename
	)

Get the database ID of a host / service entry in monarch table services.

Parameters

hostname	name of the host to search for
servicename	name of the host service to search for

Returns: service_id from table services, > 0 if the host service exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

int dassmonarch::get_host_template_id ( string host_template )

Search for a hosttemplate_id in monarch table host_templates.

Parameters

host_template name of the hosttemplate to search for

Returns: hosttemplate_id: > 0 if the host template exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

string dassmonarch::get_host_template_name ( int hosttemplate_id )

Get hosttemplatename for a given ID.

Parameters

hosttemplate_id ID of the hosttemplate to search for

Returns: hosttemplatename: the found hosttemplate name if the host template exists; otherwise, an empty string if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

arrayref or array dassmonarch::get_hostgroup_contactgroups ( string hostgroup_name )

Get a list of the contactgroups assigned to a certain hostgroup.

Parameters

hostgroup_name name of the hostgroup to search for

Returns: contactgroup_names: In list context, a list of contactgroup names, or an empty list if the hostgroup does not exist, it has no associated contactgroups, or an error occurs (the latter case being indistinguishable from the logical conditions that can generate an empty list, so this mode of calling is not robust). In scalar context, an arrayref for the list of contactgroup names (which will be legitimately empty if the hostgroup does not exist or it has no associated contactgroups), or undef if an error occurs, which makes it easy to distinguish an error condition.

int dassmonarch::get_hostgroupid ( string hostgroupname )

Find the hostgroup_id for a named hostgroup.

Parameters

hostgroupname name of the hostgroup to search for

Returns: hostgroup_id from table hostgroups, > 0 if the hostgroup exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

arrayref or array dassmonarch::get_hostgroups_for_host ( string hostname )

Retrieve a list of all hostgroups containing a given host.

Parameters

hostname name of the host for which hostgroup membership is desired

Returns: hostgroups in list context, an array of names of hostgroups containing this host

int dassmonarch::get_hostid ( string hostname )

Find the host_id for a named host.

Parameters

hostname name of the host to search for

Returns: host_id from table hosts, > 0 if the host exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

array dassmonarch::get_hostlist ( void )

Get a list of all hostnames.

Returns: hostnames: array of hostnames, or an empty list if an error occurs

string dassmonarch::get_hostname ( int host_id )

Get the hostname for a given ID.

Parameters

host_id ID of the host to search for

Returns: hostname: the found hostname; otherwise, undefined (either host not found, or database error)

int dassmonarch::get_hostprofileid ( string hostprofilename )

Find the hostprofile_id for a named hostprofile.

Parameters

hostprofilename name of the host profile to search for

Returns: hostprofile_id: > 0 if the host profile exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

string dassmonarch::get_hostprofilename ( int hostprofile_id )

Find the hostprofile name for a given hostprofile ID.

Parameters

hostprofile_id ID of the host profile to search for

Returns: name of hostprofile if hostprofile exists; otherwise, undefined

arrayref or array dassmonarch::get_hosts_in_hostgroup ( string hostgroup )

Retrieve a list of all hosts in a given hostgroup.

Parameters

hostgroup name of the hostgroup to search for

Returns: hostnames: in list context, a list of hostnames; an empty list if the hostgroup does not exist or has no host members

arrayref dassmonarch::get_hosts_with_address ( string address )

Get the names of hosts that have a given IP address.

Parameters

address IP address to search for

Returns: hostnames: arrayref pointing to a list of matching hostnames, or undef if a database error occurred

arrayref or array dassmonarch::get_hosts_with_serviceprofile ( string serviceprofilename )

Get hosts that have a certain serviceprofile assigned.

Parameters

serviceprofilename name of the serviceprofile whose associated hostnames are to be retrieved

Returns: hostids: in list context, an array of host_id values for the hosts which have the specified serviceprofile assigned, or an empty list if the search failed (e.g., due to database error); in scalar context, an arrayref to such a list, or undef if the search failed

hashref dassmonarch::get_hostservice_external	(	string	host_name,
		string	service_name,
		string	external_name
	)

Find details of an applied service external.

Parameters

host_name	Name of the host on which the service resides.
service_name	Name of the service to which the external was applied.
external_name	Name of the external to search for.

Returns: hashref pointing to details, if external exists; reference to empty hash, if the applied service external does not exist; undefined, if search failed

arrayref or array dassmonarch::get_hostservice_list ( string hostname )

Retrieve a list of all services on a host.

Parameters

hostname name of the host to get the services from

Returns: servicenames: in list context, a list of the names of services attached to this host; an empty list if the host does not exist or has no services attached

arrayref dassmonarch::get_monarch_group_hostgroups ( string monarch_group )

Tell which hostgroups are assigned to a Monarch Group.

Parameters

monarch_group name of the Monarch Group whose assigned hostgroups are to be retrieved

Returns: arrayref (names of assigned hostgroups) upon success, undef otherwise.

arrayref dassmonarch::get_monarch_group_hosts ( string monarch_group )

Tell which hosts are directly assigned to a Monarch Group.

Parameters

monarch_group name of the Monarch Group whose directly-assigned hosts are to be retrieved

Returns: arrayref (names of assigned hosts) upon success, undef otherwise.

hashref dassmonarch::get_monarch_group_orphans ( void )

Find all hosts not assigned directly or indirectly to any Monarch Group.

Returns: hashref with keys being the names of hosts not belonging to any Monarch Group, and values being true; or undef, on failure

arrayref dassmonarch::get_monarch_group_subgroups ( string monarch_group )

Tell which Monarch Groups are assigned as subgroups of a Monarch Group.

Parameters

monarch_group name of the Monarch Group whose Monarch Group subgroups are to be retrieved

Returns: arrayref (names of assigned subgroups) upon success, undef otherwise.

string dassmonarch::get_monarchgroup_location ( string monarch_group )

Get the buildpath for a Monarch Group.

Parameters

monarch_group name of the Monarch Group to get the path for

Returns: location: the path where the config files should be built; an empty string, if not set; undef if a database error occurred

arrayref or array dassmonarch::get_service_contactgroups ( string servicename )

Get a list of the contactgroups directly assigned to a certain generic service; this does not include contactgroups indirectly assigned to the generic service via service template inheritance.

Parameters

servicename name of the generic service to search for

Returns: contactgroup_names: In list context, a list of contactgroup names, or an empty list if the generic service does not exist, it has no directly associated contactgroups, or an error occurs (the latter case being indistinguishable from the logical conditions that can generate an empty list, so this mode of calling is not robust). In scalar context, an arrayref for the list of contactgroup names (which will be legitimately empty if the generic service does not exist or it has no directly associated contactgroups), or undef if an error occurs, which makes it easy to distinguish an error condition.

arrayref or array dassmonarch::get_service_hostlist ( string servicename )

Retrieve a list of all hosts having a particular service assigned.

Parameters

servicename name of the service to search for on hosts

Returns: hostnames: in list context, an array of hostnames, or an empty list if an error occurs (which is indistinguishable from having no associated hosts, so this mode of calling is not robust); in scalar context, an arrayref for the list of hostnames (which might be legitimately empty), or 0 if there was no service of that name, or undef if an error occurs, which makes it easy to distinguish an error condition

int dassmonarch::get_service_template_id ( string service_template )

Search for a servicetemplate_id in monarch table service_templates.

Parameters

service_template name of the servicetemplate to search for

Returns: servicetemplate_id: > 0 if the service template exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

int dassmonarch::get_serviceid ( string servicename )

Find the servicename_id for a named generic service.

Parameters

servicename name of the generic service to search for

Returns: servicename_id from table service_names, > 0 if the service exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

string dassmonarch::get_servicename ( int service_id )

Get the service name for a given hostservice ID.

Parameters

service_id ID of the host service to search for

Returns: servicename: the found service name; otherwise, undefined

arrayref or array dassmonarch::get_serviceprofile_services ( string serviceprofilename )

Get names of generic services assigned to a serviceprofile.

Parameters

serviceprofilename name of the serviceprofile whose assigned service names are to be retrieved

Returns: servicenames: in list context, an array of services assigned to the specified serviceprofile, or an empty list if the search failed (e.g., due to database error); in scalar context, an arrayref to such a list, or undef if the search failed

int dassmonarch::get_serviceprofileid ( string serviceprofilename )

Find the serviceprofile_id for a named serviceprofile.

Parameters

serviceprofilename name of the service profile to look for

Returns: serviceprofile_id: > 0 if the service profile exists; otherwise, 0 if the search succeeded (but found nothing), undef if the search failed (e.g., due to database error)

string dassmonarch::get_serviceprofilename ( int serviceprofile_id )

Find the serviceprofile name for a given serviceprofile ID.

Parameters

serviceprofile_id ID of the service profile to search for

Returns: profile name, false (0) otherwise

boolean or hash dassmonarch::host_exists ( string hostname )

Find out if a hostname exists.

Parameters

hostname name of the host to search for

Returns: status: in scalar context, true if the host exists, false if the host does not exist, or undef if an error occurs, which makes it easy to distinguish an error condition; in list context, a hash of the host properties, or an empty list if an error occurs (which is indistinguishable from having no such host, so this mode of calling is not robust)

boolean or hash dassmonarch::host_extinfo_template_exists ( string templatename )

Find out if a given host extended info template already exists.

Parameters

templatename name of the host extended info template to search for

Returns: status: in scalar context, true if the template exists, false if the template does not exist, or undef if an error occurs, which makes it easy to distinguish an error condition; in list context, a hash of the template properties, or an empty list if an error occurs (which is indistinguishable from having no such template, so this mode of calling is not robust)

boolean or hash dassmonarch::hostgroup_exists ( string hostgroupname )

Find out if a hostgroup exists.

Parameters

hostgroupname name of the hostgroup to search for

Returns: status: in scalar context, true if the hostgroup exists, false if the hostgroup does not exist, or undef if an error occurs, which makes it easy to distinguish an error condition; in list context, a hash of the hostgroup properties, or an empty list if an error occurs (which is indistinguishable from having no such hostgroup, so this mode of calling is not robust)

boolean dassmonarch::import_host	(	string	hostname,
		string	alias,
		string	address,
		string	profile_name,
		boolean	update
	)

Import or update a host and apply profiles. This routine performs only a shallow application of the host profile; likely, you want import_host_api() instead. If updates are disabled and you try to import an already-existing host, nothing will be changed and an error is returned. If update is allowed, all settings of an existing host will be overwritten by this import. If the host does not exist yet, it will be created with these settings, regardless of the update flag.

Parameters

hostname	name of the host to be imported
alias	the host's alias
address	the host's IP address
profile_name	name of the hostprofile to assign to the host
update	(optional) set to 1 (true), if updates to an existing host are allowed

Returns: status: true if successful, false otherwise

boolean dassmonarch::import_host_api	(	string	hostname,
		string	alias,
		string	address,
		string	profile_name,
		boolean	update
	)

Import or update a host and apply profiles using the MonarchAPI version of import_host. This routine performs a deep application of the host profile. If updates are disabled and you try to import an already-existing host, nothing will be changed and an error is returned. If update is allowed, all settings of an existing host will be overwritten by this import. If the host does not exist yet, it will be created with these settings, regardless of the update flag.

Parameters

hostname	name of the host to be imported
alias	the host's alias
address	the host's IP address
profile_name	name of the hostprofile to assign to the host
update	(optional) set to 1 (true), if updates to an existing host are allowed

Returns: status: true if successful, false otherwise

arrayref dassmonarch::list_externals ( string type )

List all free externals of a given type (host or service).

Parameters

type	Type of the external to search for ("host" or "service").

Returns: arrayref external_names pointing to list of names, if search was successful; undefined, if search failed

arrayref dassmonarch::list_host_externals ( string host_name )

List all externals assigned to a specified host.

Parameters

host_name Name of the host.

Returns: arrayref external_names pointing to list of names, if search was successful; undefined, if search failed

arrayref dassmonarch::list_hostprofile_externals ( string hostprofile_name )

List all externals assigned to a specified host profile.

Parameters

hostprofile_name Name of the host profile.

Returns: arrayref external_names pointing to list of names, if search was successful; undefined, if search failed

arrayref dassmonarch::list_hostprofiles_with_external ( string external_name )

List all host profiles with a specified external assigned.

Parameters

external_name Name of the external to search for.

Returns: arrayref hostprofile_names pointing to list of names, if search was successful; undefined, if search failed

arrayref dassmonarch::list_hosts_with_external ( string external_name )

List all hosts with a specified external assigned.

Parameters

external_name Name of the host external to search for.

Returns: arrayref host_names pointing to list of names, if search was successful; undefined, if search failed

arrayref dassmonarch::list_hostservice_externals	(	string	host_name,
		string	service_name
	)

List all externals assigned to a specified host service.

Parameters

host_name	Name of the host on which the service resides.
service_name	Name of the service.

Returns: arrayref external_names pointing to list of names, if search was successful; undefined, if search failed

arrayref dassmonarch::list_hostservices_with_external ( string external_name )

List all host services with a specified external assigned.

Parameters

external_name Name of the external to search for.

Returns: hashref hostservices pointing to hash of arrayrefs (host name keys with service name arrayref values), if search was successful; undefined, if search failed

arrayref dassmonarch::list_service_externals ( string service_name )

List all externals assigned to a specified generic service.

Parameters

service_name Name of the service.

Returns: arrayref external_names pointing to list of names, if search was successful; undefined, if search failed

arrayref dassmonarch::list_services_with_external ( string external_name )

List all generic services with a specified external assigned.

Parameters

external_name Name of the external to search for.

Returns: arrayref service_names pointing to list of names, if search was successful; undefined, if search failed

boolean dassmonarch::modify_external	(	string	external_name,
		string	description,
		string	content
	)

Modify a free external.

Parameters

external_name	Name of the external to modify.
description	Replacement comment for the external. Undefined means leave this field as-is.
content	Replacement content of the external. Undefined means leave this field as-is.

Returns: status: true if successful, false otherwise

boolean dassmonarch::modify_host_external	(	string	host_name,
		string	external_name,
		string	content,
		boolean	modified
	)

Modify a host external on a host. Overwrite existing external content and metadata.

Parameters

host_name	Name of the host on which the external is to be modified.
external_name	Name of the host external to be modified.
content	Replacement content of the external. Undefined means leave this field as-is.
modified	True, if the updated external is to be marked as a custom copy. False, if the updated external is to be marked as an unmodified copy. Undefined means leave this field as-is.

Returns: status: true if successful, false otherwise

boolean dassmonarch::modify_hostservice_external	(	string	host_name,
		string	service_name,
		string	external_name,
		string	content,
		boolean	modified
	)

Modify a service external on a host service. Overwrite existing external content and metadata.

Parameters

host_name	Name of the host on which the service resides.
service_name	Name of the host service on which the external is to be modified.
external_name	Name of the host external to be modified.
content	Replacement content of the external. Undefined means leave this field as-is.
modified	True, if the updated external is to be marked as a custom copy. False, if the updated external is to be marked as an unmodified copy. Undefined means leave this field as-is.

Returns: status: true if successful, false otherwise

boolean or hash dassmonarch::monarch_group_exists ( string monarch_group )

Find out if a given Monarch Group already exists.

Parameters

monarch_group name of the Monarch Group to search for

Returns: status: in scalar context, true if the Monarch Group exists, false if the Monarch Group does not exist, or undef if an error occurs, which makes it easy to distinguish an error condition; in list context, a hash of the Monarch Group properties, or an empty list if an error occurs (which is indistinguishable from having no such Monarch Group, so this mode of calling is not robust)

string dassmonarch::monarch_version ( void )

Get the Monarch version found by the constructor.

Returns: Full Monarch version as a string.

vstring dassmonarch::monarch_vstring ( void )

Get the Monarch version Perl vstring manufactured by the constructor.

Returns: Monarch version as a Perl vstring.

string dassmonarch::nagios_version ( void )

Get the nagios version used in constructor.

Returns: Nagios major version.

object dassmonarch::new ( void )

Returns: the new object, or die trying (meaning, you'd better encapsulate your call inside eval{};)

boolean dassmonarch::pre_flight_check ( string monarch_group )

Perform a Nagios pre-flight check.

Parameters

monarch_group name of the Monarch Group to check; undefined, to run pre-flight for the Main Configuration instead

Returns: status: true if the preflight check succeeds, false otherwise.

boolean dassmonarch::propagate_external	(	string	external_name,
		boolean	replace
	)

Propagate a free external to associated applied externals.

Parameters

external_name	Name of the external to propagate.
replace	Boolean flag; whether to update (true) or ignore (false) applied externals with their "modified" flag set.

Returns: status: true if successful, false otherwise

boolean dassmonarch::remove_contactgroup_from_servicename	(	string	contactgroup_name,
		string	servicename
	)

Remove a contactgroup from a servicename.

Parameters

contactgroup_name	name of the contactgroup to remove
servicename	name of the generic service from which the contactgroup is to be removed

Returns: status: true, if operation was successful; false otherwise

boolean dassmonarch::remove_external_from_host	(	string	host_name,
		string	external_name
	)

Remove a host external from a host.

Parameters

host_name	Name of the host.
external_name	Name of the host external.

Returns: status: true if successful, false otherwise

boolean dassmonarch::remove_external_from_hostprofile	(	string	hostprofile_name,
		string	external_name
	)

Remove a host external from a host profile.

Parameters

hostprofile_name	Name of the host profile.
external_name	Name of the host external.

Returns: status: true if successful, false otherwise

boolean dassmonarch::remove_external_from_hostservice	(	string	host_name,
		string	service_name,
		string	external_name
	)

Removes a service external from a host service.

Parameters

host_name	Name of the host.
service_name	Name of the host service from which the external is to be removed.
external_name	Name of the service external.

Returns: status: true if successful, false otherwise

boolean dassmonarch::remove_external_from_service	(	string	service_name,
		string	external_name
	)

Remove a service external from a generic service.

Parameters

service_name	Name of the service.
external_name	Name of the service external.

Returns: status: true if successful, false otherwise

boolean dassmonarch::remove_host_from_hostgroup	(	string	hostname,
		string	hostgroup
	)

Remove one host from a hostgroup.

Parameters

hostname	name of the host to be removed from the hostgroup
hostgroup	name of the hostgroup the host shall be removed from

Returns: status: true if operation successful, else false

boolean dassmonarch::remove_monarch_group_hostgroups	(	string	monarch_group,
		arrayref	hostgroups
	)

Remove specified hostgroups from a Monarch Group.

Parameters

monarch_group	name of the Monarch Group from which hostgroups are to be removed
hostgroups	reference to an array of hostgroup names, or undef to remove all hostgroups

Returns: status: true if remove_monarch_group_hostgroups completely succeeds, false otherwise.

boolean dassmonarch::remove_monarch_group_hosts	(	string	monarch_group,
		arrayref	hosts
	)

Remove specified hosts from a Monarch Group.

Parameters

monarch_group	name of the Monarch Group from which directly-assigned hosts are to be removed
hosts	reference to an array of hostnames, or undef to remove all directly-assigned hosts

Returns: status: true if remove_monarch_group_hosts completely succeeds, false otherwise.

boolean dassmonarch::remove_monarch_group_subgroups	(	string	monarch_group,
		arrayref	subgroups
	)

Remove specified subgroups from a Monarch Group.

Parameters

monarch_group	name of the Monarch Group from which Monarch Group subgroups are to be removed
subgroups	reference to an array of subgroup names, or undef to remove all subgroups

Returns: status: true if remove_monarch_group_subgroups completely succeeds, false otherwise.

boolean dassmonarch::remove_service	(	string	hostname,
		string	servicename
	)

Remove a service from a host.

Parameters

hostname	name of the host from which the service will be removed
servicename	name of the service to be removed from the host

Returns: status: true if successful, false otherwise

boolean dassmonarch::remove_serviceprofile_from_host	(	string	hostname,
		string	serviceprofilename
	)

Remove a directly-assigned service profile from a host. Will not affect services previously applied using that service profile.

Parameters

hostname	name of the host from which the serviceprofile should be removed
serviceprofilename	name of the serviceprofile to remove from the host

Returns: status: true if successful, false otherwise

boolean dassmonarch::rename_external	(	string	old_external_name,
		string	new_external_name
	)

Rename a free external.

Parameters

old_external_name	Old name of the external.
new_external_name	New name of the external.

Returns: status: true if successful, false otherwise

boolean or hash dassmonarch::search_service_by_prefix ( string substring )

This routine is misnamed; we search for service names by substring (not just prefix), because with GroundWork > 5.2 substrings match instead of prefixes and a limit count has been appended to the search statement.

Parameters

substring services whose name contains this string will be returned

Returns: services: in list context, a hash of matching service names (with identical keys and values), or an empty list if an error occurs (which is indistinguishable from having no such services, so this mode of calling is not robust); in scalar context, true if some services match, false if no services match, or undef if an error occurs, which makes it easy to distinguish an error condition

boolean or hash dassmonarch::service_exists ( string servicename )

Find out if a servicename exists.

Parameters

servicename name of the generic service to search for

Returns: status: in scalar context, true if the service exists, false if the service does not exist, or undef if an error occurs, which makes it easy to distinguish an error condition; in list context, a hash of the service properties, or an empty list if an error occurs (which is indistinguishable from having no such service, so this mode of calling is not robust)

boolean or hash dassmonarch::service_extinfo_template_exists ( string templatename )

Find out if a given service extended info template already exists.

Parameters

templatename name of the service extended info template to search for

Returns: status: in scalar context, true if the template exists, false if the template does not exist, or undef if an error occurs, which makes it easy to distinguish an error condition; in list context, a hash of the template properties, or an empty list if an error occurs (which is indistinguishable from having no such template, so this mode of calling is not robust)

boolean or hash dassmonarch::servicegroup_exists ( string servicegroupname )

Find out if a servicegroup exists.

Parameters

servicegroupname name of the servicegroup to search for

Returns: status: in scalar context, true if the servicegroup exists, false if the servicegroup does not exist, or undef if an error occurs, which makes it easy to distinguish an error condition; in list context, a hash of the servicegroup properties, or an empty list if an error occurs (which is indistinguishable from having no such servicegroup, so this mode of calling is not robust)

boolean dassmonarch::set_debuglevel ( string newlevel )

Set a new dassmonarch logging debug level.

Parameters

newlevel the new debuglevel, one of 'error', 'warning', 'info', or 'verbose'

Returns: void

boolean dassmonarch::set_generic_service_command	(	string	servicename,
		string	commandname
	)

Set the command for a named generic service.

Parameters

servicename	name of the generic service whose Nagios command should be set
commandname	name of the Nagios command that should be assigned to the generic service

Returns: status: true if successful, false otherwise

boolean dassmonarch::set_generic_service_commandline	(	string	servicename,
		string	commandline
	)

Set the commandline for a named generic service.

Parameters

servicename	name of the generic service whose commandline should be set
commandline	text of the commandline to be run for the generic service

Returns: status: true if successful, false otherwise

boolean dassmonarch::set_host_overrides_properties	(	string	hostname,
		hashref	propref
	)

Override host properties for a particular host.

Parameters

hostname	name of the host whose properties are to be overridden
propref	reference to a hash which contains key-value pairs of properties to override inherited host template settings

Returns: status: true if setting works, false otherwise

boolean dassmonarch::set_host_service_freshness_threshold	(	string	hostname,
		string	servicename,
		int	threshold
	)

Set the freshness threshold for a host service.

Parameters

hostname	name of the host on which the service resides
servicename	name of the service for which the freshness threshold should be set
threshold	freshness threshold in seconds

Returns: status: true if successful, false otherwise

boolean dassmonarch::set_host_service_notification_interval	(	string	hostname,
		string	servicename,
		int	interval
	)

Set the notification interval for a host service.

Parameters

hostname	name of the host on which the service resides
servicename	name of the service for which the notification interval should be set
interval	notification interval in seconds

Returns: status: true if successful, false otherwise

boolean dassmonarch::set_parents	(	string	hostname,
		arrayref	parents
	)

Set parents of a host.

Parameters

hostname	name of the host whose parents should be set
parents	reference to an array of parent-host names

Returns: status: true if all parents could be assigned, false otherwise

boolean dassmonarch::set_service_overrides_properties	(	string	hostname,
		string	servicename,
		hashref	propref
	)

Override service properties for a particular service definition on a particular host.

Parameters

hostname	name of the host on which the service whose properties are to be overridden resides
servicename	name of the service whose properties are to be overridden
propref	reference to a hash which contains key-value pairs of properties to override inherited service template settings

Returns: status: true if successful, false otherwise

boolean dassmonarch::update_or_insert_obj	(	string	table,
		string	searchcolumn,
		string	searchvalue,
		hashref	valref
	)

Update a database object, or create it if it does not yet exist. This method is intended for internal use within dassmonarch, and should not be used directly by applications.

Parameters

table	table to operate on
searchcolumn	column to use for searching
searchvalue	value to search for in searchcolumn
valref	hashreference for key/value pairs

Returns: status: true if successful, false otherwise

The documentation for this class was generated from the following file:

dassmonarch.pm

Public Class Methods

Public Object Methods

Detailed Description

Member Function Documentation