1. Command Line Interface
  2. Verb Reference
  3. EM CLI Verbs
  4. create_blackout

create_blackout

Creates a scheduled blackout to suspend any data collection activity on one or more monitored targets.

Format

emcli create_blackout
      -name="name"
      -add_targets="name1:type1;name2:type2;..."...
      -reason="reason"
      [-description="description"]
      [-notification_only]
      [-is_sla_required]
      [-jobs_allowed] 
      [-propagate_targets]
      [-full_blackout_all_hosts]
      [-dep_services_all]
      [-exclude_types]
      [-exclude_target]
      -schedule=
         [frequency:once|interval|weekly|monthly|yearly];
         duration:[HH...][:mm...];
         [start_time:yy-MM-dd HH:mm];
         [end_time:yy-MM-dd HH:mm];
         [repeat:#m|#h|#d|#w];
         [months:#,#,...];
         [days:#,#,...];
         [tzinfo:specified|target|repository]
         [tzoffset:#|[-][HH][:mm]]
         [tzregion:...]

[ ]  indicates that the parameter is optional

Constraints on schedule arguments:

frequency:once
    requires => duration or end_time
    optional => start_time, tzinfo, tzoffset
frequency:interval
    requires => duration, repeat
    optional => start_time, end_time, tzinfo, tzoffset
frequency:weekly
    requires => duration, days
    optional => start_time, end_time, tzinfo, tzoffset
frequency:monthly
    requires => duration, days
    optional => start_time, end_time, tzinfo, tzoffset
frequency:yearly
    requires => duration, days, months
    optional => start_time, end_time, tzinfo, tzoffset

Options

  • name

    Name of the blackout to create.

  • add_targets

    Targets to add to the blackout, each specified as target_name:target_type. You can specify this option more than once.

  • reason

    Reason for the blackout. If you have SUPER_USER privileges (you are an Enterprise Manager Super Administrator), any text string can be used for the reason. The reason is added to the list of allowable blackout reasons if it is not already in the list. If you do not have SUPER_USER privileges, you must specify one of the text strings returned by the get_blackout_reasons verb.

  • description

    Description or comments pertaining to the blackout. The description, limited to 2000 characters, can be any text string.

  • notification_only

    When this option is specified, by default a notification blackout for planned maintenance is created on the selected targets. Blackout duration is excluded from Availability(%) calculations.

  • is_sla_required

    When this option is specified, the notification blackout is created for unplanned maintenance. Blackout duration is considered for Availability(%) calculations.

  • jobs_allowed

    When you specify this option, jobs are allowed to run against blacked-out targets during the blackout period. If you do not specify this option, jobs scheduled to be run against these targets are not allowed to run during the blackout period. After a blackout has been created, you cannot change the "allowed jobs" from either EM CLI or the Enterprise Manager Cloud Control console.

  • propagate_targets

    When you specify this option, a blackout for a target of type "host" applies the blackout to all targets on the host, including the Agent. This is equivalent to nodelevel in the emctl command. Regardless of whether you specify this option, a blackout for a target that is a composite or a group applies the blackout to all members of the composite or group.

  • full_blackout_all_hosts

    When this option is specified, full blackout is enabled on all hosts included in this blackout. A full blackout places the host and all targets on the host (including the agent) under blackout. The propagate_targets option is implicitly enabled on selecting this option.

  • dep_services_all

    When this option is specified, all of the dependent targets of the targets selected for blackout will also be blacked out.

  • exclude_types

    A list of target types can be specified. Indirect members of that type and their members will not be part of the blackout. For example, specifying oracle_dbsys will exclude database systems and their members which would be otherwise indirect members of the blackout. Flags exclude_targets and exclude_types can be used in combination with one another.

  • exclude_target

    A list of indirect member targets to exclude from the blackout can be specified. Indirect members of the blackout and their members will not be part of the blackout. For example, specifying a database system target will exclude that target and the corresponding database instance from the blackout if it would otherwise be an indirect member of the blackout. Flags exclude_targets and exclude_types can be used in combination with one another.

  • schedule

    Blackout schedule. Note that the "frequency" argument determines which other arguments are required or optional.

  • schedule=frequency

    Type of blackout schedule (default is "once").

  • schedule=duration

    Duration in hours and minutes of the blackout (-1 means indefinite). Hours and minutes each can be up to 6-digits long.

  • schedule=start_time

    Start date/time of the blackout. The default value is the current date/time. The format of the value is "yy-MM-dd HH:mm", for example: "2003-09-25 18:34"

  • schedule=end_time

    Last date/time of the blackout. When "frequency" is weekly, monthly, or yearly, only the date portion is used. When "frequency" is interval or once, the date and time are taken into account. The format of the value is "yy-MM-dd HH:mm"; for example: "2003-09-25 18:34"

  • schedule=repeat

    Time between successive start times of the blackout. The letter following the number value represents the time units: "m" is minutes, "h" is hours, "d" is days, and "w" is weeks.

  • schedule=months

    List of integer month values in the range 1-12. Each value must have a corresponding "day" value to fully specify (month, day) pairs that indicate the blackout starting days of the year.

  • schedule=days

    When "frequency" is weekly, this is a list of integer day-of-week values in the range 1-7 (1 is Sunday). When "frequency" is monthly, this is a list of integer day-of-month values in the range 1-31 or -1 (last day of the month). When "frequency" is yearly, this is a list of integer day-of-month values in the range 1-31 or -1 (last day of the month); in this case, the month is taken as the corresponding "month" value for each (month, day) pair.

  • schedule=tzinfo

    Type of timezone. The tzinfo argument is used in conjunction with tzoffset. Available timezone types are: "specified" (offset between GMT and the target timezone), "target" (timezone of the specified target), and "repository" (repository timezone -- default setting when tzinfo is not specified). See -schedule=tzoffset for more information.

  • schedule=tzoffset

    Value of the timezone. When the tzinfo argument is not specified or is "repository", the timezone value is the repository timezone. In this case, the tzoffset argument must not be specified. Otherwise, the tzoffset argument is required. When tzinfo is set to "specified", the tzoffset argument specifies the offset in hours and minutes between GMT and the timezone. When tzinfo is set to "target", the tzoffset argument specifies an integer index (the first is 1) into the list of targets passed as arguments. For example, for a tzoffset setting of 1, the timezone of the first target specified in the -add_targets option is used.

    Note that the timezone is applied to the start time and the end time of the blackout periods. The timezones associated with each target are not taken into account when scheduling the blackout periods (except that when tzinfo is set to "target", the specified target's timezone is used for the blackout times).

  • schedule=[tzregion:<...>]

    Time zone region to use. When you "specify" the tzinfo option, this option determines which timezone to use for the blackout schedule. Otherwise, it is ignored. It defaults to "GMT".

Examples

Example 1

This example creates blackout b1 for the specified target (database2) to start immediately and last for 30 minutes. 

emcli create_blackout
      -name=b1
      -add_targets=database2:oracle_database
      -schedule="duration::30"
      -reason="good reason1"

Example 2

This example creates blackout b1 for the specified targets (database2 and database3) to start at 2007-08-24 22:30 and last for 30 minutes. The timezone is the timezone for the database2 target. 

emcli create_blackout
      -name=b1
      -add_targets="database2:oracle_database;database3:oracle_database
      -schedule="frequency:once;start_time:07-08-24 22:30;duration::30;tzinfo:target:tzoffset:1"
      -reason="good reason4"

Example 3

The following example creates a blackout on a WebLogic domain, but excludes the database system and its member targets.

emcli create_blackout 
      -name="wlblkout" 
      -add_targets="weblogic1:weblogic_domain" 
      -exclude_types="oracle_dbsys"
      -schedule="duration::30"
      -reason="good reason1"

Example 4

The following example creates a blackout on a group which contains hundreds of WebLogic domains. The blackout excludes database systems and its member targets (e.g. Oracle home, Listener, Database instance).

emcli create_blackout
      -name=Group_Blackout
      -add_targets="Weblogic_Domain_Group:group"
      -exclude_types=oracle_dbsys
      -schedule="duration:1:30"
      -reason="WebLogic Domain Maintenance"