Skip to main content

Configuring Calendar-Based Settings

This section describes how to set calendar-based settings. This section also illustrates their JSON syntax (used for setting advanced custom time frames). Examples of calendar-based settings include automatic- scan settings, and the host-maintenance-window setting.

Calendar-based settings are used for controlling when or how often Key Manager performs automatic jobs. Interval settings can be useful in network environments where management jobs can only be run during specific maintenance windows. Adjusting the frequency at which recurring jobs (such as automatic scans) are run can also be used to balance between having up-to-date information about the managed environment and system load.

You can set calendar-based settings according to various scheduling modes. The following list describes all the available modes. Note that not all modes are supported by each calendar-based setting.

Always​

Jobs can be performed at any time. Used only for defining maintenance windows.

General syntax in JSON format:

{
    "type": "always"
}

Never​

Never active. For maintenance windows, means that changes are prohibited. For periodic operations, no operations are automatically scheduled.

General syntax in JSON format:

{
    "type": "never"
}

Interval​

One operation per target is scheduled during each interval.

Interval value must be an integer (seconds), or a string with integers followed by time units of y (years), m (months), w (weeks), d (days), H (hours), M (minutes) or S (seconds). For example, to define an interval length of 2 days and 6 hours:

2d 6H

The interval value can also be set to 0. This disables automatic scheduling similar to the scheduling mode Never.

Whenever the setting is set, the schedule starts running from last midnight UTC. For more information about automatic job-scheduling, see Interval-Based Automatic Job Scheduling.

General syntax in JSON format:

{
    "type": "interval",
    "value": <interval>
}

As a working example, running jobs once every day:

{
    "type": "interval",
    "value": "1d"
}

Fixed​

Fixed, one-time window. For maintenance windows, allows jobs to be executed during the window. For periodic operations, one job is scheduled for the given window. The start and the end time of the window is provided as follows:

  • Via the Key Manager GUI: yyyy-mm-dd HH:MM format. For example:

    2016-10-19 20:45

  • In JSON: In absolute ISO format. For example:

    2016-10-19T20:45:00.000Z

    General syntax in JSON format:

    {
        "type": "fixed",
        "value": "<date_or_delta>..<date_or_delta>"
    }

    A working example:

    {
        "type": "fixed",
        "value": "2016-10-19T20:45:00.000Z..2016-10-21T20:45:00.000Z"
    }

Periodic Window​

Allowed job-execution windows that recur at a periodic basis. For maintenance windows, allows jobs to be executed during the specified windows. For periodic tasks, one job is scheduled for each individual window.

In periodic-window mode, the times when jobs are run is determined by the following:

  • Period: The interval at which windows recur. Each interval has one window that defines the parts of the period when jobs can be run.

  • window: The time span within each period when jobs are executed. For maintenance windows, defines the time span when jobs may be executed. For periodic tasks, one job is scheduled for each individual window.

  • Allowed days of the week or month: Specifies the days during which jobs are executed. Jobs are not executed on windows that occur during disallowed days. If not specified, jobs can be scheduled/ run on any window.

Whenever the setting is set, periods are defined in the exact same manner as intervals. For more information about automatic job-scheduling, see Interval-Based Automatic Job Scheduling.

Within each period, you must specify a window within the period for which jobs can be scheduled. The window-start and window-end parameters specify when the window starts and ends respectively. Both are to be specified as time from the beginning of the period. Window-start and window-end times must be strings with integers followed by time units y (years), m (months), w (weeks), d (days), H (hours), M (minutes) or S (seconds). For example:

2H 30M

Both the window start and the window end must be smaller than the length of the period. If the window end is set to be smaller than window start, the end of the execution window is calculated as the offset from the beginning of the next period. For more details see the examples provided later.

You can further restrict allowed execution windows by specifying the days of the week or month when windows are valid.

General syntax in JSON format:

{
    "type": "periodic_window",
    "period":  <delta>, "window_start": <delta>,
    "window_end":  <delta>,
    "weekdays": <list_of_weekdays>,
    "monthdays": <list_of_monthdays>
}

As a working example, performing jobs every day between 13:00 and 23:59:

{
    "type": "periodic_window",
    "period": "24H",   
    "window_start": "13H",
    "window_end": "23H 59M"
}

If the window end is set to be smaller than window start, the end of the execution window is calculated as the offset from the beginning of the next period. For example, performing jobs every day from 20:00 until 07:00 in next day:

{
    "type": "periodic_window",
    "period": "24H",
    "window_start": "20H",
    "window_end": "7H"
}

As another working example, performing jobs every Tuesday and Saturday between 13:00 and 23:59:

{
    "type": "periodic_window",
    "period": "24H",
    "window_start": "13H",
    "window_end": "23H 59M",
    "weekdays": [2,6]
}

Performing jobs every between 13:00 and 23:59 on certain days of the month:

{
    "type": "periodic_window",
    "period": "24H",
    "window_start": "13H",
    "window_end": "23H 59M",
    "monthdays": [4,16,28]
}

When set for a periodic operation, the following example schedules the job to be run once every three months. When set for a maintenance window, the following example allows jobs to be executed for one day every three months (starting from the day when the setting was set):

{
    "type": "periodic_window",
    "period": "3m",
    "window_start": "0d",
    "window_end": "1d"
}
note

When specifying periodic windows via the Key Manager GUI, the period length is fixed to be one day long. In this situation, window-start and window-end times effectively define the time of day when the window starts and ends.

When setting calendar-based settings via the command-line client, the value is specified as JSON, with the JSON syntax described previously (except without line breaks). For example:

$ ssh-mgr-client set-global-setting -d \
'category=host,name=scan_interval,value={"type": "interval", "value": "2H"}'
tip

In the Key Manager GUI, the currently-set JSON value of all calendar-based setting are displayed in their help (click ? next to the setting to display). To learn more about the accepted JSON syntax for calendar-based settings, you can first set a calendar-based setting using the GUI, then check the help to see the corresponding JSON.