Shutdown Manager
Shutdown Commands¶
The Shutdown Command¶
A so-called shutdown command must be associated with each monitored
Host that should be shut down by the module. This is the exact command
which will be executed by the Shutdown Manager module on the host to
shut it down. The link between monitored host and shutdown command is
created by assigning a dedicated Custom Property in the host’s
configuration form in Icinga Director.
To actually trigger the shutdown of a host, you will need to go to the Shutdown Manager module and invoke the command from there.
Each shutdown command is run using icingacli.
Shutdown commands return the result of the operation as a JSON structure. For list commands, this structure will be an array of the returned objects. For the other commands (create, delete, etc.) it will contain:
result: Whether the command succeeded or failed (‘ok’ or ‘failed’)
message: A text-based confirmation message
info: Detailed information on relevant parameters
Warning
Once you finish configuring the Shutdown Command objects, you need to deploy the Director configuration in order to execute the Commands.
Create¶
The create command lets you add a new shutdown command which you can then apply to the Shutdown command custom property of the host or host group in Director.
Usage:
# icingacli shutdownmanager shutdowncommand create [parameters]
Available Parameters:
- -name:
(mandatory) Name of the command.
- -command:
(mandatory) The command field must consist of a JSON Array that represents the command and its associated parameters needed to correctly shut down the host. If the command requires host-related parameters, the user can specify them using the pattern $<property>$, and they will be replaced by the Shutdown Manager (if correctly specified in the host definition). Currently the supported parameters are:
$host$
$hostAddress$
$hostAddress6$
$hostAlias$
$hostIpv4$
$objectType$
$hostName$
- –run-on-agent:
(mandatory) Determines whether the command should be executed on the master, or on an Icinga agent. This will only succeed if the Icinga agent is running on the host, and is connected to either the master or a satellite when the shutdown command is triggered. The value to pass is either 0 (false, i.e. run on the master) or 1 (true, i.e. run on the agent).
Edit¶
The edit command lets you change one or more values on an existing
shutdown command using the same parameters as the shutdowncommand create command
above.
Usage:
# icingacli shutdownmanager shutdowncommand edit [parameters]
List¶
The list command lets you see a list of all existing shutdown commands in JSON format.
Usage:
# icingacli shutdownmanager shutdowncommand list
Available Parameters:
- –id:
(mandatory) The ID of the definition to list
Delete¶
The delete command lets you remove a shutdown command you have created, provided that it is not in use on any hosts. It requires the shutdown command’s ID, which you can obtain from the list command.
Usage:
# icingacli shutdownmanager shutdowncommand delete [parameters]
Available Parameters:
- –id:
(mandatory) The ID of the shutdown command to delete
Triggering the Shutdown of All Hosts in a Shutdown Group¶
All hosts in a Shutdown Group can be shut down directly using this dedicated icingacli command:
icingacli shutdownmanager shutdown shutdowngroup --id <ID>
The shutdown shutdowngroup command requires the group’s ID, which
you can obtain by using the group’s list command. During command execution, all hosts in that
group will be sent their individual shutdown command.
The shutdown shutdowngroup icingacli command will return one of
the following values:
0 : Ok
1 : The mandatory ID parameter is missing
2 : The group with the given ID does not exist
3 : At least one error occurred while sending the shutdown command to the hosts in the group
Triggering the Shutdown of a Single Host¶
A single host can be shut down directly using the dedicated icingacli command:
icingacli shutdownmanager shutdown host --host-name <host name>
The shutdown host command requires a parameter for the host name.
During command execution, a check is performed which validates that the
specified host exists. In addition, the command itself verifies whether
a shutdown command has been assigned to the given host.
The Shutdown Manager will then substitute the supported macro parameters and communicate to Icinga the resulting shutdown command. Icinga will take care of executing the shutdown command.
The shutdown host icingacli command will return one of the
following values:
0 : Ok
1 : The mandatory host-name parameter is missing
2 : No hosts or more than one host was passed as the host-name parameter
3 : An error occurred while sending the shutdown command to Icinga
Shutdown Management Configuration CLI Commands¶
You can use the Shutdown Manager directly from the shell with the icingacli command.
Using the Shutdown Manager’s CLI commands, you can perform create, edit, delete and list actions on the following shutdownmanager objects:
Shutdown Definition: A Shutdown Definition that specifies how to shut down multiple computers when a condition is met.
Shutdown Group: A Shutdown Group which should all be shut down at the same time.
Below you can find detailed descriptions of the available commands and their parameters.
Shutdown Definition Commands¶
Create¶
The create command lets you construct a new shutdown definition. It requires a name and a Shutdown Condition, expressed as a Host State or a Service State depending on the command’s parameters.
Usage:
# icingacli shutdownmanager shutdowndefinition create [parameters]
Available Parameters:
- –name:
(mandatory) The name of the shutdown definition to be created.
- –host-name:
(mandatory) The name of the host whose status will trigger the shutdown, or which is running the service that will trigger the shutdown.
- –service-description:
(optional) If this parameter is empty, then the host’s status will be compared to the target status. If instead it is set to the name of a valid service on the host, then the service’s status will be used.
- –status:
(mandatory) The monitoring status that will trigger the shutdown procedure when it matches the host or service status.
Edit¶
The edit command lets you change one or more of the values for the
fields in an existing shutdown definition using the same
parameters as the shutdowndefinition
create command above.
Usage:
# icingacli shutdownmanager shutdowndefinition edit [parameters]
List¶
The list command lets you see a list of all existing shutdown definitions in JSON format.
Usage:
# icingacli shutdownmanager shutdowndefinition list
Delete¶
The delete command lets you remove an existing shutdown definition given that definition’s ID, which you can obtain from the list command.
Usage:
# icingacli shutdownmanager shutdowndefinition delete [parameters]
Available Parameters:
- –id:
(mandatory) The ID of the definition to delete
Shutdown of a definition¶
The shutdowndefinition command lets you trigger the shutdown of a pre-configured shutdown definition.
Once a shutdown group is triggered, a timer will count down while the hosts in that shutdown group are powering down. Once the timeout period has expired, the subsequent shutdown group will be triggered and its timer set, until no more shutdown groups remain.
Usage:
# icingacli shutdownmanager shutdown shutdowndefinition [parameters]
Available Parameters:
- –id:
(mandatory) The ID of the shutdown definition which has to be shutdown
Shutdown Group Commands¶
Create¶
The create command lets you construct a new shutdown group. It requires a name, a set of monitored objects, a shutdown definition to belong to, and an ordering relative to other groups.
Usage:
# icingacli shutdownmanager shutdowngroup create [parameters]
Available Parameters:
- –name:
(mandatory) The name of the shutdown group to be created.
- –filter:
(mandatory) A monitoring filter that will return a set of monitored objects to be included in this new group.
- –shutdown-definition-id:
(mandatory) The ID of a shutdown definition (obtainable via the list command) which this new group will then belong to.
- –timeout:
(mandatory) The number of seconds after which the shutdown process for the next group will be initiated.
- –group-order:
(optional) A number representing the order of this group relative to other groups in the shutdown definition. Lower-numbered groups are shut down before higher-numbered groups, and any groups having the same order number in the shutdown definition will be shut down in a random order relative to themselves. If no group order parameter is specified, then the value will default to the next highest available number (for instance, if you have only one group with order 3 in the definition, the new group will have order 4). If no groups yet exist in the shutdown definition, it will be set to
1.
Edit¶
The edit command lets you change one or more values for the fields
in an existing shutdown group using the same parameters as the shutdowngroup create command
above.
Usage:
# icingacli shutdownmanager shutdowngroup edit [parameters]
List¶
The list command lets you see all existing shutdown groups in JSON format.
Usage:
# icingacli shutdownmanager shutdowngroup list
Available Parameters: None
Delete¶
The delete command lets you remove an existing shutdown group given that group’s ID, which you can obtain from the list command.
Usage:
# icingacli shutdownmanager shutdowngroup delete [parameters]
Available Parameters:
- –id:
(mandatory) The ID of the group to delete
Listhosts¶
The listhosts command lets you see all hosts that belong to a shutdown group in JSON format. Each entry in the output list represents a host and contains:
The host name
The host address
The ID of the shutdown command associated with the host (null if the host is not associated with any shutdown command)
Usage:
# icingacli shutdownmanager shutdowngroup listhosts [parameters]
Available Parameters:
- –id:
(mandatory) The ID of the shutdown group whose hosts are to be displayed
