Cisco IOS Software Releases 12.3 Mainline

Table Of Contents

Command Scheduler

Contents

Restrictions for Command Scheduler

Information About Command Scheduler

Command Scheduler Overview

How to Configure Command Scheduler

Configuring Command Scheduler Policy Lists

Command Scheduler Policy Lists

Prerequisites

Configuring Command Scheduler Occurrences

Command Scheduler Occurrences

Prerequisites

Restrictions

Examples

Troubleshooting Tips

Configuration Examples for Command Scheduler

Configuring Command Scheduler Examples

Where to Go Next

Additional References

Related Documents

Standards

MIBs

RFCs

Technical Assistance

Command Reference

cli

debug kron

kron occurrence

kron policy-list

policy-list

show kron schedule

Command Scheduler

---

The Command Scheduler feature provides the ability to schedule some EXEC command-line interface (CLI) commands to run at specific times or at specified intervals.

Feature Specifications for the Command Scheduler

Feature History
Release	Modification
12.3(1)	This feature was introduced.
Supported Platforms
For platforms supported in Cisco IOS Release 12.3(1), consult Cisco Feature Navigator.

Finding Support Information for Platforms and Cisco IOS Software Images

Use Cisco Feature Navigator to find information about platform support and Cisco IOS software image support. Access Cisco Feature Navigator at http://www.cisco.com/go/fn. You must have an account on Cisco.com. If you do not have an account or have forgotten your username or password, click Cancel at the login dialog box and follow the instructions that appear.

Contents

•Restrictions for Command Scheduler

•Information About Command Scheduler

•How to Configure Command Scheduler

•Configuration Examples for Command Scheduler

•Where to Go Next

•Additional References

•Command Reference

Restrictions for Command Scheduler

The EXEC CLI specified in a Command Scheduler policy list must not generate a prompt or have the ability to be terminated using keystrokes. Command Scheduler is designed as a fully automated facility and no manual intervention is permitted.

Information About Command Scheduler

To configure Command Scheduler, you need to understand the following concept:

•Command Scheduler Overview

Command Scheduler Overview

Command Scheduler allows customers to schedule fully-qualified EXEC mode CLI commands to run once, at specified intervals, or at specified calendar dates and times. Originally designed to work with CNS commands, Command Scheduler has a broader application. Using the CNS image agent feature, remote routers residing outside a firewall or using Network Address Translation (NAT) addresses can use Command Scheduler to launch CLI at intervals to update the image running in the router.

Command Scheduler has two basic processes. A policy list is configured containing lines of fully-qualified EXEC CLI to be run at the same time or interval. One or more policy lists are then scheduled to run after a specified interval of time or at a specified calendar date and time. Each scheduled occurrence can be set to run once only or on a recurring basis.

How to Configure Command Scheduler

This section contains the following procedures:

•Configuring Command Scheduler Policy Lists (required)

•Configuring Command Scheduler Occurrences (required)

Configuring Command Scheduler Policy Lists

Use this task to set up the lists of EXEC commands to be run at the same time or at the same interval.

Command Scheduler Policy Lists

Policy lists consist of one or more lines of fully-qualified EXEC CLI commands. All commands in a policy list are executed when the policy list is run by Command Scheduler using the kron occurrence command. Use separate policy lists for CLI commands to be run at different times. No editor function is available and the policy list is run in the order in which it was configured. To delete an entry, use the no form of the cli command followed by the appropriate EXEC command. If an existing policy list name is used, new entries are added to the end of the policy list. To view entries in a policy list, use the show running-config command. If a policy list is scheduled to run only once, it will not be displayed by the show running-config command after it has run.

Policy lists can be configured after the policy list has been scheduled, but each policy list must be configured before it is scheduled to run.

Prerequisites

The EXEC CLI to be run by Command Scheduler must be tested on the routing device to determine if it will run without generating a prompt or allowing execution interruption by keystrokes. Initial testing is important because Command Scheduler will delete the entire policy list if any CLI syntax fails. Removing the policy list ensures that any CLI dependencies will not generate more errors.

SUMMARY STEPS

1. enable

2. configure terminal

3. kron policy-list list-name

4. cli command

5. Repeat Step 4 for all EXEC CLI to run at the same time or interval.

6. exit

DETAILED STEPS

	Command or Action	Purpose
Step 1	enable Example: Router> enable	Enables privileged EXEC mode. •Enter your password if prompted.
Step 2	configure terminal Example: Router# configure terminal	Enters global configuration mode.
Step 3	kron policy-list list-name Example: Router(config)# kron policy-list cns-weekly	Specifies a name for a new or existing Command Scheduler policy list and enters kron-policy configuration mode. •If the list-name is new, a new policy list structure is created. •If the list-name exists, the existing policy list structure is accessed. The policy list is run in configured order with no editor function.
Step 4	cli command Example: Router(config-kron-policy)# cli cns image retrieve server http://10.19.2.3/cnsweek/ status http://10.19.2.3/cnsstatus/week/	Specifies the fully-qualified EXEC command and associated syntax to be added as an entry in the specified Command Scheduler policy list. •Each entry is added to the policy list in the order in which it is configured. Note EXEC commands that generate a prompt or can be terminated using keystrokes will result in an error on execution.
Step 5	Repeat Step 4. Example: Router(config-kron-policy)# cli cns config retrieve	Repeat Step 4 to add other EXEC CLI commands to a policy list to be executed at the same time or interval. •Each entry is added to the policy list in the order in which it is configured. Note EXEC commands that generate a prompt or can be terminated using keystrokes will result in an error on execution.
Step 6	exit Example: Router(config-kron-policy)# exit	Exits kron-policy configuration mode, and returns the router to global configuration mode.

Configuring Command Scheduler Occurrences

Use this task to schedule one or more Command Scheduler policy lists to run at a specific date and time or recurring interval.

Command Scheduler Occurrences

An occurrence for Command Scheduler is defined as a scheduled event. Policy lists are configured to run after a period of time since the scheduling was set, or at a specified calendar date and time. Policy lists can be run once, as a one-time event, or as recurring events over time.

Command scheduler occurrences can be scheduled before the associated policy list has been configured, but a warning will advise you to configure the policy list before it is scheduled to run.

Prerequisites

The clock time must be set on the routing device before a Command Scheduler occurrence is scheduled to run. If the clock time is not set, a warning message will appear on the console screen after the kron occurrence command has been entered. Use the clock command or Network Time Protocol (NTP) to set the clock time.

Restrictions

•No more than 31 policy lists can be scheduled to run at the same time.

•If a one-time occurrence is scheduled, the occurrence will not be displayed by the show running-config command after the occurrence has run.

SUMMARY STEPS

1. enable

2. configure terminal

3. kron occurrence occurrence-name [user user-name] {in [[numdays:]numhours:]nummin | at hours:min [[month] day-of-month] [day-of-week]} {oneshot | recurring}

4. policy-list list-name

5. Repeat Step 4 for all policies to run at the same time or interval.

6. end

7. show kron schedule

DETAILED STEPS

	Command or Action	Purpose
Step 1	enable Example: Router> enable	Enables privileged EXEC mode. •Enter your password if prompted.
Step 2	configure terminal Example: Router# configure terminal	Enters global configuration mode.
Step 3	kron occurrence occurrence-name [user user] {in [[numdays:]numhours:]nummin | at hours:min [[month] day-of-month] [day-of-week]} {oneshot | recurring} Example: Router(config)# kron occurrence may user sales at 6:30 may 20 oneshot	Specifies a name and schedule for a new or existing Command Scheduler occurrence and enters kron-occurrence configuration mode. •If the occurrence-name is new, a new occurrence list structure is created. •If the occurrence-name exists, the existing occurrence structure is accessed. The occurrence is run in configured order with no editor function. •Use the in keyword to specify a delta time interval with a timer that starts when this command is configured. •Use the at keyword to specify a calendar date and time.
Step 4	policy-list list-name Example: Router(config-kron-occurrence)# policy-list sales-may	Specifies a Command Scheduler policy list. •Each entry is added to the occurrence list in the order in which it is configured. Note If the CLI commands in a policy list generate a prompt or can be terminated using keystrokes, an error will be generated and the policy list will be deleted on the execution of the occurrence.
Step 5	Repeat Step 4. Example: Router(config-kron-occurrence)# policy-list itd-may	Repeat Step 4 to add other Command Scheduler policies to be executed at the same time or interval. •Each entry is added to the occurrence list in the order in which it is configured. Note If the CLI commands in a policy generate a prompt or can be terminated using keystrokes, an error will be generated and the policy will be deleted on the execution of the occurrence.
Step 6	exit Example: Router(config-kron-occurrence)# exit	Exits kron-occurrence configuration mode, and returns the router to global configuration mode. •Repeat this step one more time to exit global configuration mode.
Step 7	show kron schedule Example: Router# show kron schedule	Displays the status and schedule information of Command Scheduler occurrences.

Examples

In the following example, output information is displayed about the status and schedule of all configured Command Scheduler occurrences:

Router# show kron schedule

Kron Occurrence Schedule

cns-weekly inactive, will run again in 7 days 01:02:33 

may inactive, will run once in 32 days 20:43:31 at 6:30 on May 20

Troubleshooting Tips

Use the debug kron command in privileged EXEC mode to troubleshoot Command Scheduler command operations. Use any debugging command with caution as the volume of output generated can slow or stop the router operations.

Configuration Examples for Command Scheduler

This section contains the following configuration example:

•Configuring Command Scheduler Examples

Configuring Command Scheduler Examples

In the following example, a Command Scheduler policy named cns-weekly is configured to run two sets of EXEC CLI involving CNS commands. The policy is then scheduled with two other policies to run every seven days, one hour and thirty minutes.

kron policy-list cns-weekly

 cli cns image retrieve server http://10.19.2.3/week/ status http://10.19.2.5/status/week/

 cli cns config retrieve page /testconfig/config.asp no-persist

!

kron occurrence week in 7:1:30 recurring

 policy-list cns-weekly

 policy-list itd-weekly

 policy-list mkt-weekly

In the following example, a Command Scheduler policy named sales-may is configured to run a CNS command to retrieve a specified image from a remote server. The policy is then scheduled to run only once on May 20, at 6:30 a.m.

kron policy-list sales-may

 cli cns image retrieve server 10.19.2.3 status 10.19.2.3

!

kron occurrence may at 6:30 May 20 oneshot

 policy-list sales-may

In the following example, a Command Scheduler policy named image-sunday is configured to run a CNS command to retrieve a specified image from a remote server. The policy is then scheduled to run every Sunday at 7:30 a.m.

kron policy-list image-sunday

 cli cns image retrieve server 10.19.2.3 status 10.19.2.3

!

kron occurrence sunday user sales at 7:30 sunday recurring

 policy-list image-sunday

Where to Go Next

One area of application for the Command Scheduler process is working with CNS services such as CNS image agent. See the "Related Documents" section for more details.

Additional References

The following sections provide additional information related to Command Scheduler:

•Related Documents

•Standards

•MIBs

•RFCs

•Technical Assistance

Related Documents

Related Topic	Document Title
CNS commands: complete command syntax, command mode, defaults, usage guidelines, and examples	"CNS Commands" chapter in the Cisco IOS Configuration Fundamentals and Network Management Command Reference, Release 12.3
CNS image agent feature	"CNS Image Agent" feature document, Release 12.3(1)

Standards

Standards	Title
No new or modified standards are supported by this feature, and support for existing standards has not been modified by this feature.	—

MIBs

MIBs	MIBs Link
No new or modified MIBs are supported by this feature, and support for existing MIBs has not been modified by this feature.	To locate and download MIBs for selected platforms, Cisco IOS releases, and feature sets, use Cisco MIB Locator found at the following URL: http://www.cisco.com/go/mibs

RFCs

RFCs	Title
No new or modified RFCs are supported by this feature, and support for existing RFCs has not been modified by this feature.	—

Technical Assistance

Description	Link
Technical Assistance Center (TAC) home page, containing 30,000 pages of searchable technical content, including links to products, technologies, solutions, technical tips, and tools. Registered Cisco.com users can log in from this page to access even more content.	http://www.cisco.com/public/support/tac/home.shtml

Command Reference

This section documents new commands. All other commands used with this feature are documented in the Cisco IOS Release 12.3 command reference publications.

•cli

•debug kron

•kron occurrence

•kron policy-list

•policy-list

•show kron schedule

cli

To specify EXEC command line interface (CLI) commands within a Command Scheduler policy list, use the cli command in kron-policy configuration mode. To delete a CLI command from the current policy list, use the no form of this command.

cli command

no cli command

Syntax Description

command

EXEC mode CLI command syntax. Commands must not generate a prompt or allow interruption by any keystroke.

Defaults

No CLI commands are specified.

Command Modes

Kron-policy configuration

Command History

Release	Modification
12.3(1)	This command was introduced.

Usage Guidelines

Use the cli command in conjunction with the kron policy-list command to create a policy list containing EXEC CLI commands to be scheduled to run on the router at a specified time. Use the kron occurrence and policy-list commands to schedule one or more policy lists to run at the same time or interval.

The Command Scheduler process is useful to automate the running of EXEC commands at recurring intervals, and it can be used in remote routers to minimize manual intervention.

Examples

The following example shows how to configure the EXEC command cns image retrieve within the policy list named three-day-list:

Router(config)# kron policy-list three-day-list

Router(config-kron-policy)# cli cns image retrieve server http://10.19.2.3/cns/image/ 
status http://10.19.2.3/cnsstatus/imageinfo/

Related Commands

Command	Description
kron occurrence	Specifies schedule parameters for a Command Scheduler occurrence and enters kron-occurrence configuration mode.
kron policy-list	Specifies a name for a Command Scheduler policy and enters kron-policy configuration mode.
policy-list	Specifies the policy list associated with a Command Scheduler occurrence.

debug kron

To display debugging messages about Command Scheduler policies or occurrences, use the debug kron command in privileged EXEC mode. To disable debugging output, use the no form of this command.

debug kron {all | exec-cli | info | major}

no debug kron {all | exec-cli | info | major}

Syntax Description

all	Displays all debugging output about Command Scheduler policy lists or occurrences.
exec-cli	Displays detailed debugging output about Command Scheduler policy list command line interface (CLI) commands.
info	Displays debugging output about Command Scheduler policy lists, occurrence warnings, or progress information.
major	Displays debugging output about Command Scheduler policy list or occurrence failures.

Defaults

If no keyword is specified, all debugging messages are displayed.

Command Modes

Privileged EXEC

Command History

Release	Modification
12.3(1)	This command was introduced.

Usage Guidelines

Use the debug kron command to display the output of a scheduled EXEC show command on the console.

Examples

The following example shows debugging messages for the EXEC CLI show version after the CLI was run at a scheduled interval:

Router# debug kron exec-cli

Kron cli occurrence messages debugging is on

2w6d: Call parse_cmd 'show version'

2w6d: Kron CLI return 0

'

**CLI 'show version': 

Cisco Internetwork Operating System Software IOS (tm) C2600 Software (C2600-I-M

.

.

.

Related Commands

Command	Description
show kron schedule	Displays the status and schedule information for Command Scheduler occurrences.

kron occurrence

To specify schedule parameters for a Command Scheduler occurrence and enter kron-occurrence configuration mode, use the kron occurrence command in global configuration mode. To delete a Command Scheduler occurrence, use the no form of this command.

kron occurrence occurrence-name [user username] {in [[numdays:] numhours:] nummin | at hours:min [[month] day-of-month] [day-of-week]} {oneshot | recurring | system-startup}

no kron occurrence occurrence-name [user username] {in [[numdays:] numhours:] nummin | at hours:min [[month] day-of-month] [day-of-week]} {oneshot | recurring | system-startup}

Syntax Description

occurrence-name	Name of the occurrence. The length of occurrence-name is from 1 to 31 characters. If the occurrence-name is new, an occurrence structure will be created. If the occurrence-name is not new, the existing occurrence will be edited.
user	(Optional) Identifies a particular user.
username	(Optional) Name of the user.
in	Indicates that the occurrence is to run after a specified time interval. The timer starts when the occurrence is configured.
numdays:	(Optional) Number of days. If used, add a colon after the number.
numhours:	(Optional) Number of hours. If used, add a colon after the number.
nummin	Number of minutes.
at	Indicates that the occurrence is to run at a specified calendar date and time.
hours:	Hour as a number using the twenty-four hour clock. Add a colon after the number.
min	Minute as a number.
month	(Optional) Month name. If used, you must also specify day-of-month.
day-of-month	(Optional) Day of month as a number.
day-of-week	(Optional) Day of week name.
oneshot	Indicates that the occurrence is to run only one time. After the occurrence has run, the configuration is removed.
recurring	Indicates that the occurrence is to run on a recurring basis.
system-startup	(Optional) Indicates that the occurrence is to run on system startup, in addition to the recurring or oneshot occurrences.

Command Default

No schedule parameters are specified.

Command Modes

Global configuration (config)

Command History

Release	Modification
12.3(1)	This command was introduced.
12.2(33)SRA	This command was integrated into Cisco IOS Release 12.2(33)SRA.
12.4(15)T	The system-startup keyword was added. The user keyword and username argument were removed from this command in Cisco IOS Release 12.4(15)T.

Usage Guidelines

Prior to Cisco IOS Release 12.4, when you configured a kron occurrence for a calendar time when the system clock was not set, you received a printf message stating that the clock was not set and the occurrence would not be scheduled until it was set.

Beginning in Cisco IOS Release 12.4, when you configure a kron occurrence for a calendar time when the system clock is not set, the occurrence is scheduled but a printf message appears stating that the clock is not set and that it currently reads <current clock time>.

If you set the clock, the schedule of the occurrence is affected in one of the following ways:

•A new clock time set for less than 3 hours after the occurrence is scheduled to happen causes the occurrence to happen immediately.

•A new clock time set for less than 3 hours before the occurrence is scheduled to happen causes the occurrence to happen as scheduled.

•A new clock time set for more than 3 hours after the occurrence is scheduled to happen causes the occurrence to be rescheduled for the next regular calendar time.

•A new clock time set for more than 3 hours before the occurrence is scheduled to happen causes the occurrence to be rescheduled for the previous regular calendar time.

Use the kron occurrence and policy-list commands to schedule one or more policy lists to run at the same time or interval.

Use the kron policy-list command in conjunction with the cli command to create a Command Scheduler policy containing EXEC command-line interface (CLI) commands to be scheduled to run on the router at a specified time.

Use the show kron schedule command to display the name of each configured occurrence and when it will next run.

The Command Scheduler process is useful to automate the running of EXEC commands at recurring intervals, and it can be used in remote routers to minimize manual intervention.

Examples

The following example shows how to create a Command Scheduler occurrence named info-three and schedule it to run every three days, 10 hours, and 50 minutes. The EXEC CLI in the policy named three-day-list is configured to run as part of occurrence info-three.

Router(config)# kron occurrence info-three user IT2 in 3:10:50 recurring

Router(config-kron-occurrence)# policy-list three-day-list

The following example shows how to create a Command Scheduler occurrence named auto-mkt and schedule it to run once on June 4 at 5:30 a.m. The EXEC CLI in the policies named mkt-list and mkt-list2 are configured to run as part of occurrence auto-mkt.

Router(config)# kron occurrence auto-mkt user marketing at 5:30 jun 4 oneshot

Router(config-kron-occurrence)# policy-list mkt-list

Router(config-kron-occurrence)# policy-list mkt-list2

Related Commands

Command	Description
cli	Specifies EXEC CLI commands within a Command Scheduler policy list.
kron policy-list	Specifies a name for a Command Scheduler policy and enters kron-policy configuration mode.
policy-list	Specifies the policy list associated with a Command Scheduler occurrence.
show kron schedule	Displays the status and schedule information for Command Scheduler occurrences.

kron policy-list

To specify a name for a Command Scheduler policy and enter kron-policy configuration mode, use the kron policy-list command in global configuration mode. To delete the policy list, use the no form of this command.

kron policy-list list-name

no kron policy-list list-name

Syntax Description

list-name

Name of policy. Length of list-name is from 1 to 31 characters. If the list-name is new, a policy list structure will be created. If the list-name is not new, the existing policy list will be edited.

Defaults

If the specified list name does not exist, a new policy list is created.

Command Modes

Global configuration

Command History

Release	Modification
12.3(1)	This command was introduced.

Usage Guidelines

Use the kron policy-list command in conjunction with the cli command to create a Command Scheduler policy containing EXEC command line interface (CLI) commands to be scheduled to run on the router at a specified time. Use the kron occurrence and policy-list commands to schedule one or more policy lists to run at the same time or interval.

The Command Scheduler process is useful to automate the running of EXEC commands at recurring intervals, and it can be used in remote routers to minimize manual intervention.

Examples

The following example shows how to create a policy named sales-may and configure EXEC CLI commands to run the CNS command that retrieves an image from a server:

Router(config)# kron policy-list sales-may

Router(config-kron-policy)# cli cns image retrieve server http://10.21.2.3/imgsvr/ status 
http://10.21.2.5/status/

Related Commands

Command	Description
cli	Specifies EXEC CLI commands within a Command Scheduler policy list.
kron occurrence	Specifies schedule parameters for a Command Scheduler occurrence and enters kron-occurrence configuration mode.
policy-list	Specifies the policy list associated with a Command Scheduler occurrence.

policy-list

To associate a policy list with a Command Scheduler occurrence, use the policy-list command in kron-occurrence configuration mode. To delete a policy list from the Command Scheduler occurrence, use the no form of this command.

policy-list list-name

no policy-list list-name

Syntax Description

list-name

Name of policy list. If the list-name is new, a policy list structure will be created. If the list-name is not new, the existing policy list will be edited.

Defaults

No policy list is associated.

Command Modes

Kron-occurrence configuration

Command History

Release	Modification
12.3(1)	This command was introduced.

Usage Guidelines

Use the policy-list command with the kron occurrence command to schedule one or more policy lists to run at the same time or interval. Use the kron policy-list command in conjunction with the cli command to create a Command Scheduler policy list containing EXEC command line interface (CLI) commands to be scheduled to run on the router at a specified time.

The Command Scheduler process is useful to automate the running of EXEC commands at recurring intervals, and can it be used in remote routers to minimize manual intervention.

Examples

The following example shows how to create a Command Scheduler occurrence named may and associate a policy list named sales-may with the occurrence:

Router(config)# kron occurrence may at 6:30 may 20 oneshot

Router(config-kron-occurrence)# policy-list sales-may

Related Commands

Command	Description
cli	Specifies EXEC CLI commands within a Command Scheduler policy list.
kron occurrence	Specifies schedule parameters for a Command Scheduler occurrence and enters kron-occurrence configuration mode.
policy-list	Specifies a name for a Command Scheduler policy and enters kron-policy configuration mode.

show kron schedule

To display the status and schedule information of Command Scheduler occurrences, use the show kron schedule command in user EXEC or privileged EXEC mode.

show kron schedule

Syntax Description

This command has no arguments or keywords.

Command Modes

User EXEC
Privileged EXEC

Command History

Release	Modification
12.3(1)	This command was introduced.

Usage Guidelines

Use the show kron schedule command to view all currently configured occurrences and when they are next scheduled to run.

Examples

The following sample output displays each configured policy name and the time interval before the policy is scheduled to run:

Router# show kron schedule

Kron Occurrence Schedule

week inactive, will run again in 7 days 01:02:33 

may inactive, will run once in 32 days 20:43:31 at 6:30 on Jun 20

Table 1 describes the significant fields shown in the display.

Table 1 show kron schedule Field Descriptions 

Field	Description
week inactive	The policy list named week is currently inactive.
run again in 7 days 01:02:33	Time in days, hours, minutes and seconds before the policy will run. This policy is scheduled to run on a recurring basis.
run once in 32 days 20:434:31	Time in days, hours, minutes and seconds before the policy will run. This policy is scheduled to run just once.

Related Commands

Command	Description
kron occurrence	Specifies schedule parameters for a Command Scheduler occurrence and enters kron-occurrence configuration mode.
policy-list	Specifies the policy list associated with a Command Scheduler occurrence.

Copyright © 2003-2007 Cisco Systems, Inc. All rights reserved.