| 1 | # Time Periods |
| 2 | |
| 3 | Time periods control **when** a Nagios check job is allowed to run. Each time period is a named schedule with one or more allow rules. |
| 4 | |
| 5 | - Outside the active time period, the check does not execute and its state becomes `paused`. |
| 6 | - The built-in `24x7` period (always allowed) is the default `check_period`. |
| 7 | - Set the `check_period` option in a job to reference a named time period. |
| 8 | - Define custom time periods using the `time_periods` option within the same job. |
| 9 | |
| 10 | ## Rule Types |
| 11 | |
| 12 | | Type | Description | Key Fields | |
| 13 | |:--------------|:---------------------------------------|:---------------------------| |
| 14 | | `weekly` | Repeats on specific weekdays | `days`, `ranges` | |
| 15 | | `nth_weekday` | Nth occurrence of a weekday in a month | `weekday`, `nth`, `ranges` | |
| 16 | | `date` | Specific calendar dates | `dates`, `ranges` | |
| 17 | |
| 18 | ### Fields |
| 19 | |
| 20 | - **`days`** — List of weekday names: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday` |
| 21 | - **`ranges`** — List of time ranges in `HH:MM-HH:MM` format (e.g., `"09:00-18:00"`). Use `"00:00-24:00"` for all day. |
| 22 | - **`weekday`** — Single weekday name (for `nth_weekday` rules) |
| 23 | - **`nth`** — Which occurrence of the weekday in the month (1 = first, 2 = second, etc.) |
| 24 | - **`dates`** — List of calendar dates in `YYYY-MM-DD` format |
| 25 | - **`exclude`** — List of other time period names to subtract from this period |
| 26 | |
| 27 | ## Examples |
| 28 | |
| 29 | ### Business hours (Mon–Fri, 09:00–18:00) |
| 30 | |
| 31 | ```yaml |
| 32 | time_periods: |
| 33 | - name: business_hours |
| 34 | alias: Business Hours |
| 35 | rules: |
| 36 | - type: weekly |
| 37 | days: [monday, tuesday, wednesday, thursday, friday] |
| 38 | ranges: ["09:00-18:00"] |
| 39 | ``` |
| 40 | |
| 41 | ### First Monday maintenance window each month |
| 42 | |
| 43 | ```yaml |
| 44 | time_periods: |
| 45 | - name: first_monday_maintenance |
| 46 | alias: First Monday Maint |
| 47 | rules: |
| 48 | - type: nth_weekday |
| 49 | weekday: monday |
| 50 | nth: 1 |
| 51 | ranges: ["02:00-04:00"] |
| 52 | ``` |
| 53 | |
| 54 | ### Holiday blackout by specific dates |
| 55 | |
| 56 | ```yaml |
| 57 | time_periods: |
| 58 | - name: holidays |
| 59 | alias: Holiday Blackout |
| 60 | rules: |
| 61 | - type: date |
| 62 | dates: ["2026-12-25", "2026-12-31"] |
| 63 | ranges: ["00:00-24:00"] |
| 64 | ``` |
| 65 | |
| 66 | ### Always allowed, except during maintenance and holidays |
| 67 | |
| 68 | ```yaml |
| 69 | time_periods: |
| 70 | - name: run_checks |
| 71 | alias: Run Checks |
| 72 | rules: |
| 73 | - type: weekly |
| 74 | days: [sunday, monday, tuesday, wednesday, thursday, friday, saturday] |
| 75 | ranges: ["00:00-24:00"] |
| 76 | exclude: [first_monday_maintenance, holidays] |
| 77 | ``` |
| 78 | |
| 79 | ## Notes |
| 80 | |
| 81 | - Date format is strict `YYYY-MM-DD`. |
| 82 | - Time range format is strict `HH:MM-HH:MM`. `24:00` is valid only as an end boundary. |
| 83 | - The built-in `24x7` period is always available and is the default `check_period`. |