3. Module Overview
Questa sezione conserva il testo RFC sul ietf-schedule YANG model, includendo recurrence groupings, iCalendar-like rules, schedule status groupings, DISMAN-SCHEDULE-MIB relationship, IANA registrations, YANG/XML examples e scheduled resource examples.
Testo RFC originale
3. Module Overview
3.1. Features
The "ietf-schedule" data model defines the recurrence-related
groupings using a modular approach. To that aim, a variety of
representations of recurrence groupings ranging from basic to
advanced (iCalender-like) are defined. To allow for different
options, two features are defined in the data model:
* "basic-recurrence"
* "icalendar-recurrence"
Refer to Section 3.4 and Appendix B.1 for the use of these features.
3.2. Types and Identities
The "ietf-schedule" module (Section 6) defines the following
identities:
* "schedule-type": Indicates the type of schedule. The following
types are defined so far:
- one-shot: This type is used for a schedule that triggers an
action that has either the duration specified as 0 or the end
time specified as the same as the start time, and then the
schedule will disable itself (Section 3.3 of [RFC3231]).
- period: This type is used for a period-based schedule
consisting of either (1) a start and end or (2) a start and
positive duration of time. If neither an end nor a duration is
indicated, the period is considered to last forever.
- recurrence: This type is used for a recurrence-based schedule.
A recurrence may be periodic (i.e., repeat over the same
period, e.g., every five minutes) or not (i.e., repeat in a
non-regular manner, e.g., every day at 8 and 9 AM).
* "frequency-type": Characterizes the repeating interval rule of a
recurrence schedule (secondly, minutely, etc.).
* "schedule-state": Indicates the status of a schedule (enabled,
disabled, conflicted, finished, etc.). This identity can also be
used to manage the state of individual instances of a recurrence-
based schedule.
* "discard-action-type": Specifies the action for the responder to
take (e.g., generate a warning or an error message) when a
requested schedule cannot be accepted for any reason and is
discarded.
3.3. Scheduling Groupings
The "ietf-schedule" module (Section 6) defines the following
groupings:
* "generic-schedule-params" (Section 3.3.1)
* "period-of-time" (Section 3.3.2)
* "recurrence-basic" (Section 3.3.3)
* "recurrence-utc" (Section 3.3.4)
* "recurrence-with-time-zone" (Section 3.3.5)
* "recurrence-utc-with-periods" (Section 3.3.6)
* "recurrence-time-zone-with-periods" (Section 3.3.7)
* "icalendar-recurrence" (Section 3.3.8)
* "schedule-status", "schedule-status-with-time-zone", and
"schedule-status-with-name" (Section 3.3.9)
Examples are provided in Appendix A.
3.3.1. The "generic-schedule-params" Grouping
A system accepts and handles schedule requests, which may help
further automate the scheduling process of events, policies,
services, or resources based on date and time. The "generic-
schedule-params" grouping (Figure 1) specifies a set of configuration
parameters that are used by a system for validating requested
schedules.
grouping generic-schedule-params:
+-- description? string
+-- time-zone-identifier? sys:timezone-name
+-- validity? yang:date-and-time
+-- max-allowed-start? yang:date-and-time
+-- min-allowed-start? yang:date-and-time
+-- max-allowed-end? yang:date-and-time
+-- discard-action? identityref
Figure 1: 'generic-schedule-params' Grouping Tree Structure
The "description" parameter includes a description of the schedule.
No constraint is imposed on the structure nor the use of this
parameter.
The "time-zone-identifier" parameter, if provided, specifies the time
zone reference [RFC7317] of the local date and time values. This
parameter MUST be specified if any of the date and time values are in
the format of local time. It MUST NOT be applied to date and time
values that are specified in the format of UTC or time zone offset to
UTC.
The "validity" parameter specifies the date and time after which a
schedule will not be considered as valid. It determines the latest
time that a schedule can be started and thus executed independently
from when it ends, and it takes precedence over similar attributes
that are provided at the schedule instance itself. A requested
schedule may still be accepted, but any occurrences that start later
than the configured value will not be executed.
The "max/min-allowed-start" parameters specify the maximum/minimum
scheduled start date and time. A requested schedule will be rejected
if the first occurrence of the schedule starts later/earlier than the
configured values.
The "max-allowed-end" parameter specifies the maximum allowed end
time of the last occurrence. A requested schedule will be rejected
if the end time of the last occurrence is later than the configured
"max-allowed-end" value.
The "discard-action" parameter specifies the action if a requested
schedule cannot be accepted for any reason and is discarded.
Possible reasons include, but are not limited to, the requested
schedule failing to satisfy the guards in this grouping, conflicting
with existing schedules, or being out-of-date (e.g., the expected
start has already passed).
These parameters apply to all schedules on a system and are meant to
provide guards against stale configuration, schedule requests that
are too short and that would thus prevent validation by admins of
some critical systems, etc.
3.3.2. The "period-of-time" Grouping
The "period-of-time" grouping (Figure 2) represents a time period
using either a start date and time ("period-start") and end date and
time ("period-end") or a start date and time ("period-start") and a
non-negative time duration ("duration"). For the first format, the
start of the period MUST be no later than the end of the period. If
neither an end date and time ("period-end") nor a duration
("duration") is indicated, the period is considered to last forever.
If the duration ("duration") value is 0 or the end time ("period-
end") is the same as the start time ("period-start"), the period is
considered as a one-shot schedule. If no start date and time
("period-start") is specified, the period is considered to start
immediately.
The "time-zone-identifier" parameter indicates the identifier for the
time zone. This parameter MUST be specified if either the "period-
start" or "period-end" value is reported in local time format. It
MUST NOT be applied to date and time values that are specified in the
format of UTC or time zone offset to UTC.
The "period-description" parameter includes a description of the
period. No constraint is imposed on the structure nor the use of
this parameter.
grouping period-of-time:
+-- period-description? string
+-- period-start? yang:date-and-time
+-- time-zone-identifier? sys:timezone-name
+-- (period-type)?
+--:(explicit)
| +-- period-end? yang:date-and-time
+--:(duration)
+-- duration? duration
Figure 2: 'period-of-time' Grouping Tree Structure
3.3.3. The "recurrence-basic" Grouping
The "recurrence-basic" grouping (Figure 3) specifies a simple
recurrence rule that starts immediately and repeats forever.
grouping recurrence-basic:
+-- recurrence-description? string
+-- frequency? identityref
+-- interval? uint32
Figure 3: 'recurrence-basic' Grouping Tree Structure
The frequency parameter ("frequency") identifies the type of
recurrence rule. For example, a "daily" frequency value specifies
repeating events based on an interval of a day or more.
Consistent with Section 3.3.10 of [RFC5545], the interval parameter
("interval") represents at which interval the recurrence rule
repeats. For example, within a "daily" recurrence rule, an interval
value of "8" means every eight days.
Note that, per Section 4.13 of [YANG-GUIDE], no "default"
substatement is defined here for both "frequency" and "interval"
parameters because there are cases (e.g., profiling) where using
these statements is problematic. No "mandatory" substatement is
defined here for the same reason. YANG modules using this grouping
SHOULD refine these two nodes with either a "mandatory" or a
"default" statement if they always need to be configured or have
default values. This recommendation MAY be ignored in cases such as
when this grouping is used by another grouping.
The "recurrence-description" parameter includes a description of the
period. No constraint is imposed on the structure nor the use of
this parameter.
3.3.4. The "recurrence-utc" Grouping
The "recurrence-utc" grouping (Figure 4) uses the "recurrence-basic"
grouping (Section 3.3.3) and specifies a simple recurrence rule in
UTC format.
grouping recurrence-utc:
+-- recurrence-first
| +-- start-time-utc? yang:date-and-time
| +-- duration? uint32
+-- (recurrence-end)?
| +--:(until)
| | +-- utc-until? yang:date-and-time
| +--:(count)
| +-- count? uint32
+-- recurrence-description? string
+-- frequency? identityref
+-- interval? uint32
Figure 4: 'recurrence-utc' Grouping Tree Structure
The "start-time-utc" parameter indicates the start time in UTC
format.
The "duration" parameter specifies, in units of seconds, the time
period of the first occurrence. Unless specified otherwise (e.g.,
through additional augmented parameters), the "duration" also applies
to subsequent recurrence instances. When unspecified, each
occurrence is considered as immediate completion (e.g., execute an
immediate command that is considered to complete quickly) or hard to
compute an exact duration (e.g., run a data analysis script whose
execution time may depend on the data volume and computation resource
availability). The behavior to follow when a task takes more time
than specified by the "duration" is out of scope. Such
considerations belong to task management, not schedule management.
Note that the "interval" and "duration" cover two distinct properties
of a schedule event. The interval specifies when a schedule will
occur, combined with the frequency parameter, while the duration
indicates how long an occurrence will last. This document allows the
interval between occurrences to be shorter than the duration of each
occurrence (e.g., a recurring event is scheduled to start every day
for a duration of 2 days).
The repetition can be scoped by a specified end time or by a count of
occurrences, indicated by the "recurrence-end" choice. The "count"
value MUST be greater than 1, and the "start-time-utc" value always
counts as the first occurrence.
The "recurrence-utc" grouping is designed to be reused in scheduling
contexts where machine readability is more desirable.
3.3.5. The "recurrence-with-time-zone" Grouping
The "recurrence-with-time-zone" grouping (Figure 5) uses the
"recurrence-basic" grouping (Section 3.3.3) and specifies a simple
recurrence rule with a time zone.
grouping recurrence-with-time-zone:
+-- recurrence-first
| +-- start-time? yang:date-and-time
| +-- duration? duration
+-- time-zone-identifier? sys:timezone-name
+-- (recurrence-end)?
| +--:(until)
| | +-- until? yang:date-and-time
| +--:(count)
| +-- count? uint32
+-- recurrence-description? string
+-- frequency? identityref
+-- interval? uint32
Figure 5: 'recurrence-with-time-zone' Grouping Tree Structure
The "recurrence-first" container includes "start-time" and "duration"
parameters to specify the start time and period of the first
occurrence. Unless specified otherwise (e.g., through additional
augmented parameters), the "duration" also applies to subsequent
recurrence instances. When unspecified, each occurrence is
considered as immediate completion (e.g., execute an immediate
command that is considered to complete quickly) or hard to compute an
exact duration (e.g., run a data analysis script whose execution time
may depend on the data volume and computation resource availability).
The grouping also includes a "time-zone-identifier" parameter, which
MUST be specified if either the "start-time" or "until" value is
reported in local time format. It MUST NOT be applied to date and
time values that are specified in the format of UTC or time zone
offset to UTC.
The repetition can be scoped by a specified end time or by a count of
occurrences, indicated by the "recurrence-end" choice. The "count"
value MUST be greater than 1, and the "start-time" value always
counts as the first occurrence.
The considerations discussed in Section 3.3.4 for "interval" and
"duration" are also applicable to "recurrence-with-time-zone".
Unlike the definition of the "recurrence-utc" grouping
(Section 3.3.4), "recurrence-with-time-zone" is intended to promote
human readability over machine readability.
3.3.6. The "recurrence-utc-with-periods" Grouping
The "recurrence-utc-with-periods" grouping (Figure 6) uses the
"recurrence-utc" grouping (Section 3.3.4) and adds a "period-
timeticks" list to define an aggregate set of repeating occurrences.
grouping recurrence-utc-with-periods:
+-- recurrence-first
| +-- start-time-utc? yang:date-and-time
| +-- duration? uint32
+-- (recurrence-end)?
| +--:(until)
| | +-- utc-until? yang:date-and-time
| +--:(count)
| +-- count? uint32
+-- recurrence-description? string
+-- frequency? identityref
+-- interval? uint32
+-- period-timeticks* [period-start]
+-- period-start yang:timeticks
+-- period-end? yang:timeticks
Figure 6: 'recurrence-utc-with-periods' Grouping Tree Structure
The recurrence instances are specified by the union of occurrences
defined by both the recurrence rule and "period-timeticks" list.
This list uses the "yang:timeticks" type defined in [RFC9911].
Duplicate instances are ignored. The value of the "period-start"
instance MUST NOT exceed the value of the "frequency" instance, i.e.,
the "timeticks" value must not exceed 100 in a secondly recurrence
rule, and it must not exceed 6000 in a minutely recurrence rule, and
so on.
3.3.7. The "recurrence-time-zone-with-periods" Grouping
The "recurrence-time-zone-with-periods" grouping (Figure 7) uses the
"recurrence-with-time-zone" grouping (Section 3.3.5) and adds a
"period" list to define an aggregate set of repeating occurrences.
grouping recurrence-time-zone-with-periods:
+-- recurrence-first
| +-- start-time? yang:date-and-time
| +-- duration? duration
+-- time-zone-identifier? sys:timezone-name
+-- (recurrence-end)?
| +--:(until)
| | +-- until? yang:date-and-time
| +--:(count)
| +-- count? uint32
+-- recurrence-description? string
+-- frequency? identityref
+-- interval? uint32
+-- period* [period-start]
+-- period-description? string
+-- period-start yang:date-and-time
+-- time-zone-identifier? sys:timezone-name
+-- (period-type)?
+--:(explicit)
| +-- period-end? yang:date-and-time
+--:(duration)
+-- duration? duration
Figure 7: 'recurrence-time-zone-with-periods' Grouping Tree Structure
The recurrence instances are specified by the union of occurrences
defined by both the recurrence rule and "period" list. Duplicate
instances are ignored.
3.3.8. The "icalendar-recurrence" Grouping
The "icalendar-recurrence" grouping (Figure 8) uses the "recurrence-
time-zone-with-periods" grouping (Section 3.3.7) and defines more
data nodes to enrich the definition of recurrence. The structure of
the "icalendar-recurrence" grouping refers to the definition of the
recurrence component defined in Sections 3.3.10 and 3.8.5 of
[RFC5545].
grouping icalendar-recurrence:
+-- recurrence-first
| +-- start-time? yang:date-and-time
| +-- duration? duration
+-- time-zone-identifier? sys:timezone-name
+-- (recurrence-end)?
| +--:(until)
| | +-- until? yang:date-and-time
| +--:(count)
| +-- count? uint32
+-- recurrence-description? string
+-- frequency? identityref
+-- interval? uint32
+-- period* [period-start]
| +-- period-description? string
| +-- period-start yang:date-and-time
| +-- time-zone-identifier? sys:timezone-name
| +-- (period-type)?
| +--:(explicit)
| | +-- period-end? yang:date-and-time
| +--:(duration)
| +-- duration? duration
+-- bysecond* uint32
+-- byminute* uint32
+-- byhour* uint32
+-- byday* [weekday]
| +-- direction* int32
| +-- weekday schedule:weekday
+-- bymonthday* int32
+-- byyearday* int32
+-- byyearweek* int32
+-- byyearmonth* uint32
+-- bysetpos* int32
+-- workweek-start? schedule:weekday
+-- exception-dates* yang:date-and-time
Figure 8: 'icalendar-recurrence' Grouping Tree Structure
An array of the "bysecond" (or "byminute" or "byhour") specifies a
list of seconds within a minute (or minutes within an hour or hours
of the day). For example, within a "minutely" recurrence rule, the
values of "byminute" node "10" and "20" mean the occurrences are
generated at the 10th and 20th minute within an hour, reducing the
number of recurrence instances from all minutes.
The parameter "byday" specifies a list of days of the week, with an
optional direction that indicates the nth occurrence of a specific
day within the "monthly" or "yearly" frequency instance. Valid
values of "direction" are 1 to 5 or -5 to -1 within a "monthly"
recurrence rule and 1 to 53 or -53 to -1 within a "yearly" recurrence
rule. For example, within a "monthly" rule, the "weekday" with a
value of "monday" and the "direction" with a value of "-1" represents
the last Monday of the month.
An array of the "bymonthday" (or byyearday", "byyearweek", or
"byyearmonth") specifies a list of days of the month (or days of the
year, weeks of the year, or months of the year). For example, within
a "yearly" recurrence rule, the values of "byyearmonth" instances "1"
and "2" mean the occurrences are generated in January and February,
increasing the "yearly" recurrence from every year to every January
and February of the year.
The "bysetpos" conveys a list of values that corresponds to the nth
occurrence within the set of recurrence instances to be specified.
For example, in a "monthly" recurrence rule, the "byday" data node
specifies every Monday of the week, and the "bysetpos" with a value
of "-1" represents the last Monday of the month. Not setting the
"bysetpos" data node represents every Monday of the month.
The "workweek-start" data node specifies the day on which the week
starts. This is significant when a "weekly" recurrence rule has an
interval greater than 1, and a "byday" data node is specified. This
is also significant when in a "yearly" rule and a "byyearweek" is
specified. Note that, per Section 4.13 of [YANG-GUIDE], no "default"
substatement is defined here because there are cases (e.g.,
profiling) where using these statements is problematic. No
"mandatory" substatement is defined here for the same reason. YANG
modules using this grouping SHOULD refine the "workweek-start" node
with either a "mandatory" or a "default" statement if it always needs
to be configured or has a default value. This MAY be ignored in
cases such as when this grouping is used by another grouping.
The "exception-dates" data node specifies a list of exceptions for
recurrence. The final recurrence set is generated by gathering all
of the date and time values created by any of the specified
recurrence rules and date-times and then excluding any start date and
time values specified by "exception-dates" parameter.
3.3.9. The "schedule-status", "schedule-status-with-time-zone", and
"schedule-status-with-name" Groupings
The "schedule-status", "schedule-status-with-time-zone", and
"schedule-status-with-name" groupings (Figure 9) define common
parameters for scheduling management/status exposure. The "schedule-
status-with-time-zone" grouping has the same structure as "schedule-
status" but with an additional parameter to identify a time zone.
Similarly, the "schedule-status-with-name" grouping has the same
structure as "schedule-status" but with an additional parameter to
identify a schedule "schedule-name". These structures are defined in
the module to allow for better modularity and flexibility.
grouping schedule-status:
+-- state? identityref
+-- version? uint16
+-- schedule-type? identityref
+--ro local-time? yang:date-and-time
+--ro last-update? yang:date-and-time
+--ro counter? yang:counter32
+--ro last-occurrence? yang:date-and-time
+--ro upcoming-occurrence? yang:date-and-time
+--ro last-failed-occurrence? yang:date-and-time
+--ro failure-counter? yang:counter32
grouping schedule-status-with-time-zone:
+--ro time-zone-identifier? sys:timezone-name
+-- schedule-name? string
+-- state? identityref
+-- version? uint16
+-- schedule-type? identityref
+--ro local-time? yang:date-and-time
+--ro last-update? yang:date-and-time
+--ro counter? yang:counter32
+--ro last-occurrence? yang:date-and-time
+--ro upcoming-occurrence? yang:date-and-time
+--ro last-failed-occurrence? yang:date-and-time
+--ro failure-counter? yang:counter32
grouping schedule-status-with-name:
+-- schedule-name? string
+-- state? identityref
+-- version? uint16
+-- schedule-type? identityref
+--ro local-time? yang:date-and-time
+--ro last-update? yang:date-and-time
+--ro counter? yang:counter32
+--ro last-occurrence? yang:date-and-time
+--ro upcoming-occurrence? yang:date-and-time
+--ro last-failed-occurrence? yang:date-and-time
+--ro failure-counter? yang:counter32
Figure 9: 'schedule-status-*' Groupings Tree Structure
The "schedule-name" parameter is useful to uniquely identify a
schedule in a network device or controller if multiple scheduling
contexts exist.
The "state" parameter is defined to configure/expose the scheduling
state, depending on the use of the grouping. For a recurrence-based
schedule, it represents the state of the overall recurrence. The
"identityref" type is used for this parameter to allow extensibility
in future modules.
The "version" parameter is used to track the current schedule version
information. The version can be incremented by the entity that
created the schedule. The "last-update" parameter identifies when
the schedule was last modified. In some contexts, this parameter can
be used to track the configuration of a given schedule. In such
cases, the "version" may not be used.
The "schedule-type" parameter identifies the type of the current
schedule. The "counter", "last-occurrence", and "upcoming-
occurrence" data nodes are only available when the "schedule-type" is
"recurrence".
When no time zone is included, "local-time" reports the actual local
time as seen by the entity that hosts a schedule. This parameter can
be used by a controller to infer the offset to UTC. This use is
similar to the use of "schedLocalTime" in [RFC3231].
"last-failed-occurrence" and "failure-counter" report the last
failure that occurred and the count of failures for this schedule.
Unless new parameters/operations are defined to allow the count of
failures to be reset, "failure-counter" is reset by default only when
the schedule starts.
The current groupings capture common parameters that are applicable
to typical scheduling contexts known so far. Future modules can
define other useful parameters as needed. For example, in a
scheduling context with multiple system sources to feed the
schedules, the "source" and "precedence" parameters may be needed to
reflect how schedules from different sources should be prioritized.
3.4. Features Use and Augmentations
Appendix B.1 provides an example about how the features defined in
Section 3.1 can be used. Implementations may support a basic
recurrence rule or an advanced one, as needed, by declaring different
features. Whether only one or both features are supported is
implementation specific and depends on the specific scheduling
context.
The common schedule groupings (Section 3.3) can also be augmented to
support specific needs. As an example, Appendix B.2 demonstrates how
additional parameters can be added to comply with specific schedule
needs.