Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/wikioasis/salt/llms.txt

Use this file to discover all available pages before exploring further.

The host Salt execution module provides Icinga2 API integration for scheduling monitoring downtimes directly from Salt. Its primary use is suppressing alerts on hosts and all their associated services before a deployment or maintenance operation, preventing alert fatigue and on-call noise during intentional disruptions. All API calls go directly to the Icinga2 master over HTTPS.

​
Pillar Configuration

The module reads its connection settings from the monitoring pillar key. All keys must be set on the minion that will execute the function (i.e. the minion that Salt runs the module on, not necessarily the host being downtimed). 
# pillar
monitoring:
  icinga_api_host: icinga2-master.ovvin.wonet
  icinga_api_user: root
  icinga_api_password: "changeme"
  icinga_api_port: 5665
​
monitoring:icinga_api_host
string
required
Hostname or IP address of the Icinga2 master node. The module constructs the API URL as https://<icinga_api_host>:<icinga_api_port>/v1/....
​
monitoring:icinga_api_user
string
default:"root"
Icinga2 API username for HTTP Basic authentication. Defaults to root.
​
monitoring:icinga_api_password
string
required
Icinga2 API password. A CommandExecutionError is raised at call time if this key is missing or empty.
​
monitoring:icinga_api_port
integer
default:"5665"
TCP port of the Icinga2 API listener. Defaults to 5665.

​
Functions

​
host.downtime(hostname, duration, reason)

Schedules a fixed downtime in Icinga2 for the named host and all of its services. Alerts are suppressed for the duration of the downtime. The all_services: 1 flag in the API payload ensures that every service check associated with the host is covered by a single API call — you do not need to schedule services individually. The downtime is recorded as a “fixed” downtime (as opposed to flexible), meaning it starts immediately when scheduled and ends at now + duration regardless of whether the host state changes.
​
hostname
string
required
The Icinga2 host object name. This must match the host.name attribute in Icinga2 exactly — typically the FQDN, e.g. mw-us-east-011.ovvin.wonet.
​
duration
string | integer
required
Length of the downtime. Accepts:
  • A plain integer or numeric string (interpreted as seconds): 3600, "3600"
  • A string with a unit suffix: "30s", "30m", "2h", "1d"
SuffixUnitExampleSeconds
sseconds"90s"90
mminutes"30m"1 800
hhours"2h"7 200
ddays"1d"86 400
​
reason
string
required
Free-text comment recorded against the downtime in Icinga2. Visible in the Icinga2 web interface and included in downtime notifications. Use a descriptive message so on-call staff can understand why the host was downtimed.
Returns: A summary string confirming how many objects were downtimed: 
Downtime scheduled for 'mw-us-east-011.ovvin.wonet' + 14 service(s) — 2h for 'Deploying new code'
Raises CommandExecutionError if:
  • monitoring:icinga_api_host or monitoring:icinga_api_password are missing from pillar
  • The Icinga2 API returns a non-200 HTTP status
  • The API returns an empty results list (host not found in Icinga2)
  • Any result in the response has a non-200 Icinga2 status code

​
CLI Examples

# 2-hour downtime for a deployment
salt '*' host.downtime 'mw-us-east-011.ovvin.wonet' '2h' 'Deploying new code'

# 30-minute downtime for a quick service restart
salt '*' host.downtime 'mw-us-east-011.ovvin.wonet' '30m' 'Quick restart'

# 1-day downtime for extended maintenance
salt '*' host.downtime 'mw-us-east-011.ovvin.wonet' '1d' 'Extended maintenance'

# Downtime using plain seconds
salt '*' host.downtime 'mw-us-east-011.ovvin.wonet' 3600 'Rolling deploy window'

# Target specific minions when running from the Salt master
salt 'mw-us-east-011*' host.downtime 'mw-us-east-011.ovvin.wonet' '1h' 'OS patching'
The salt '*' target in these examples refers to which Salt minion executes the module (and therefore which minion’s monitoring pillar is used for API credentials). It does not need to match the Icinga2 hostname being downtimed. You can run host.downtime from any minion that has the monitoring pillar keys set, including the Salt master itself via salt-call.

​
Duration Format Reference

The _parse_duration helper tries the suffix format first, then falls back to bare integer parsing: 
# These are all equivalent (1 hour = 3600 seconds):
host.downtime 'host.example.com' '3600'   'reason'
host.downtime 'host.example.com' 3600     'reason'
host.downtime 'host.example.com' '60m'    'reason'
host.downtime 'host.example.com' '1h'     'reason'
An invalid duration (e.g. "2x", "abc") raises a CommandExecutionError immediately with the message: 
Invalid duration '2x' — use seconds or a suffix: s/m/h/d

​
Common Workflows

​
Downtime before a rolling deploy

Schedule downtime on every MediaWiki server before starting a deploy, then clear it after: 
# Downtime all app servers for the expected deploy window
for host in mw-us-east-011.ovvin.wonet mw-us-east-012.ovvin.wonet \
            mw-us-east-021.ovvin.wonet mw-us-east-022.ovvin.wonet; do
  salt '*' host.downtime "$host" '1h' 'Rolling MediaWiki deploy'
done
Or use a Salt compound command if your minion names match the Icinga2 host names: 
salt 'mw-us-east-*' host.downtime "$(hostname -f)" '1h' 'Rolling MediaWiki deploy'

​
Downtime before OS patching

salt '*' host.downtime 'task-us-east-011.ovvin.wonet' '2h' 'OS patching — kernel update'

​
Downtime from the Salt master with salt-call

If running interactively on the Salt master: 
salt-call host.downtime 'proxy-us-east-011.ovvin.wonet' '30m' 'HAProxy config change'

​
API Payload Details

For reference, the module posts the following JSON payload to https://<icinga_api_host>:5665/v1/actions/schedule-downtime: 
{
  "type": "Host",
  "filter": "host.name == \"mw-us-east-011.ovvin.wonet\"",
  "start_time": 1736951530,
  "end_time": 1736958730,
  "duration": 7200,
  "fixed": true,
  "comment": "Deploying new code",
  "author": "root",
  "all_services": 1
}
The author field is set to icinga_api_user from pillar (default root). SSL certificate verification is disabled (verify_ssl: False) to support self-signed Icinga2 API certificates typical in internal deployments.

Build docs developers (and LLMs) love

Get started for freeTalk to us