> Section: [4. Configuration](https://jaque.sh/docs/config/cue-in-practice.md)
> Next: config/hot-reload
> Index: https://jaque.sh/llms.txt


A downtime is a window during which an object's notifications are
silenced and every event in that window is marked as expected rather
than as a surprise. jaque schedules three kinds: fixed, which silences a
window you name up front; flexible, which starts only once the object
actually has a problem inside that window; and triggered, which starts
and stops with another downtime. A fourth shape, recurring, is declared
in config rather than scheduled: an object is in downtime whenever a
named timeperiod is open.

## 1. Fixed downtimes

The window is the downtime: from `start` it silences the object, and at
`end` it stops, whether or not anything went wrong in between. This is
what `SCHEDULE_HOST_DOWNTIME`/`SCHEDULE_SVC_DOWNTIME` and the API's
`ScheduleDowntime` give you when no other kind is asked for.

## 2. Flexible downtimes

A flexible downtime carries a `start`, an `end` and a `duration`. It does
not silence anything by itself: it starts the first time the object
enters a problem status inside `[start, end)`, and then it lasts
`duration` from that point, which can run past `end`. The window only
bounds when it may start. An object that never has a problem inside the
window never enters downtime at all.

## 3. Triggered downtimes

A triggered downtime names another downtime as its trigger and carries
its own `start` and `end` as a cap. It starts the moment its trigger
downtime starts, and it ends at whichever comes first: its own `end`, or
the trigger's own end. Cancelling the trigger cancels every downtime it
triggered.

## 4. Taking effect, and catching up after a restart

Whenever a downtime actually takes effect, that is a fact jaque records:
a fixed downtime at its start time, a flexible one the moment a problem
puts it into effect, a triggered one the moment its trigger takes
effect. An engine that was not running at the moment a boundary would
have been crossed does at startup what it would have done had it been
up: a fixed downtime whose start has already passed takes effect
immediately; a flexible downtime whose window is still open re-checks
the object's current status; a triggered downtime re-checks whether its
trigger is currently in effect. Nothing here is rederived from wall-clock
arithmetic against the log; it is the same check the engine would have
made at the time.

## 5. Recurring downtimes

A recurring downtime is not scheduled at all: it is declared in config,
against a selector and a timeperiod, and every object the selector
matches is in downtime whenever that timeperiod is open.

```cue
timeperiods: {
	backup_window: {
		timezone: "Europe/Madrid"
		ranges: {sunday: "02:00-04:00"}
	}
}

downtimes: {
	nightly_backup: {
		selector: "role=db"
		scope:    "service"
		period:   "backup_window"
		comment:  "nightly backup"
	}
}
```

`selector` is a [label selector](https://jaque.sh/docs/config/labels-and-views.md); `scope` is `host`
or `service`, and it must match at least one object of that scope or the
config fails to load. `period` names a [timeperiod](https://jaque.sh/docs/config/timeperiods.md).
Nothing about a recurring downtime is written to the event log or
persisted between occurrences: being in downtime is simply whether the
period is open right now. It cannot be scheduled, edited or cancelled
through the API or the FIFO, and it is never a trigger for another
downtime. Every read surface, the dashboard, the API and Livestatus,
shows the occurrence currently in effect, or the next one if none is,
the same way it shows any other downtime's window.

## 6. What `<fixed>` and `<trigger_id>` mean on the FIFO

`SCHEDULE_HOST_DOWNTIME` and `SCHEDULE_SVC_DOWNTIME` carry the same
`<fixed>` and `<trigger_id>` fields Nagios always used, and jaque now
acts on both instead of rejecting anything but a fixed downtime:

- `<fixed>=1`, `<trigger_id>=0` schedules a fixed downtime.
- `<fixed>=0`, `<trigger_id>=0` schedules a flexible downtime; `<duration>`
  is read as a positive number of seconds.
- `<fixed>=1`, a nonzero `<trigger_id>` schedules a triggered downtime,
  with `<trigger_id>` as the downtime it triggers on; `<duration>` is
  still read off the line for its position but has no effect.
- `<fixed>=0` together with a nonzero `<trigger_id>` is a parse error: a
  downtime cannot be both flexible and triggered.

See [FIFO external commands](https://jaque.sh/docs/nagios-compat/fifo-external-commands.md)
for the full field list of every downtime verb.