Cron Expressions

Overview

Cron expressions define the schedule for all automated tasks in NetStacks. They use the standard 5-field format to specify exactly when a task should run — from every minute to once a year. Every scheduled task stores a cron expression alongside a timezone identifier so that schedules behave correctly across time zones and daylight saving transitions.

Cron Expression Format (5 fields)

  ┌───────────── minute (0-59)
  │ ┌───────────── hour (0-23)
  │ │ ┌───────────── day of month (1-31)
  │ │ │ ┌───────────── month (1-12)
  │ │ │ │ ┌───────────── day of week (0-6, Sunday = 0)
  │ │ │ │ │
  * * * * *

NetStacks uses the standard 5-field cron format. Each field accepts numbers, wildcards, ranges, lists, and step values. The Controller parses and validates expressions when you create or update a scheduled task.

How It Works

Cron Parsing

When you save a scheduled task, the Controller parses the cron expression and calculates the next run time relative to the specified timezone. The result is stored in the next_run_at field as a UTC timestamp. After each execution, the scheduler recalculates next_run_at for the following occurrence.

Timezone Handling

All cron expressions are evaluated in the context of a timezone. The timezone field accepts any valid IANA timezone identifier (e.g., America/New_York, Europe/London, Asia/Tokyo, or UTC). The Controller handles daylight saving transitions automatically — a task scheduled for 2:00 AM will run at 2:00 AM local time regardless of DST changes.

Next-Run Prediction

The task creation and editing UI shows the next 5 calculated run times so you can verify the expression produces the schedule you expect. This preview accounts for the selected timezone and current date.

Writing Cron Expressions

Step 1: Understand Each Field

Step 2: Use Special Characters

Step 3: Set the Timezone

Always pair your cron expression with a timezone. Use IANA timezone names like America/New_York, America/Chicago, America/Los_Angeles, or UTC. The timezone determines when the expression fires relative to local time.

Step 4: Preview Next Runs

After entering an expression and timezone in the task editor, review the preview showing the next 5 scheduled runs. If the times do not match your expectations, adjust the expression or timezone before saving.

Code Examples

Common Cron Patterns for Network Operations

Health Check Every 15 Minutes

# Cron: */15 * * * *
# Timezone: UTC
# Runs at :00, :15, :30, :45 every hour
# Use case: Monitor reachability of branch edge switches

Minute:       */15   (every 15th minute)
Hour:         *      (every hour)
Day of Month: *      (every day)
Month:        *      (every month)
Day of Week:  *      (every day of the week)

Nightly Backup at 2 AM Eastern

# Cron: 0 2 * * *
# Timezone: America/New_York
# Runs at 2:00 AM ET (7:00 AM UTC, or 6:00 AM UTC during EDT)
# Use case: Capture running-config from core-rtr-01.dc1, core-rtr-02.dc1,
#           dist-sw-01.dc1, dist-sw-02.dc1 into config-snapshots/

Minute:       0      (at the top of the hour)
Hour:         2      (2 AM local time)
Day of Month: *      (every day)
Month:        *      (every month)
Day of Week:  *      (every day of the week)

Weekday Business Hours Only

# Cron: 0 9-17 * * 1-5
# Timezone: America/Chicago
# Runs every hour from 9 AM to 5 PM, Monday through Friday
# Use case: Hourly interface error counter check during business hours

Minute:       0      (at the top of each hour)
Hour:         9-17   (9 AM through 5 PM)
Day of Month: *      (every day)
Month:        *      (every month)
Day of Week:  1-5    (Monday through Friday)

Questions & Answers

Q: What cron format does NetStacks use?

A: NetStacks uses the standard 5-field cron format: minute, hour, day of month, month, and day of week. Each field supports wildcards (*), ranges (1-5), lists (0,30), and step values (*/15). This is the same format used by Unix crontab.

Q: How do I handle timezones in cron expressions?

A: Every scheduled task has a timezone field that accepts IANA timezone identifiers like America/New_York or Europe/London. The cron expression is evaluated in the context of that timezone. Internally, the Controller converts all times to UTC for storage and scheduling, but the expression always fires at the local time you specified, even across daylight saving transitions.

Q: How do I schedule a task for the last day of the month?

A: Standard cron does not have a "last day of month" keyword. The most common workaround is to schedule for days 28-31 and accept that the task runs on all those days, or schedule for day 1 of the next month with the understanding that it runs at the start of each month instead. For example, 0 23 28-31 * * runs at 11 PM on the 28th through 31st of each month.

Q: Can I see when my cron expression will next run?

A: Yes. The task editor in the NetStacks UI shows a preview of the next 5 scheduled run times based on your cron expression and selected timezone. After saving, the task detail view displays the calculated next_run_at timestamp.

Q: What is the minimum interval for scheduled tasks?

A: The shortest supported cron interval is every minute (* * * * *), but this is not recommended for production use. For health checks and monitoring tasks, a 5-minute or 15-minute interval is typical. For backups and deployments, daily or weekly schedules are standard. Running tasks too frequently can overload target devices and consume Controller resources.

Q: Can I use day names or month names in cron expressions?

A: NetStacks uses numeric values for all cron fields. Use 0-6 for days of the week (Sunday = 0, Saturday = 6) and 1-12 for months (January = 1, December = 12). The UI provides labels alongside the numeric fields to help you select the correct values.

Troubleshooting

Task running at the wrong time

This is almost always a timezone mismatch. Verify the timezone field on the task matches your intended local time. Check the next_run_at value in the task details — this is the UTC timestamp the scheduler will use. Convert it to your local timezone to confirm it aligns with the cron expression. Remember that daylight saving transitions shift the UTC offset by one hour.

Expression not matching expected schedule

The most common mistake is confusing the field order. The fields are: minute, hour, day-of-month, month, day-of-week. For example, 30 2 * * * means "at 2:30 AM" (minute 30, hour 2), not "every 30 minutes at 2 AM." Use the preview feature in the task editor to verify your expression before saving.

Overlapping executions

If a previous task run has not finished by the time the next scheduled run triggers, the new execution enters the queue and waits. This can cause a backlog if the task consistently takes longer than its interval. Solution: increase the cron interval, optimize the task to run faster, or increase the timeout so tasks complete before the next run.

Related Features

Learn more about scheduling and automation in NetStacks:

• Scheduled Tasks — Create and manage cron-scheduled tasks for backups, health checks, and deployments
• Task Monitoring — Track execution status, view logs, and monitor retry attempts
• Method of Procedures (MOPs) — Multi-step procedures with approval workflows for complex changes
• NOC Agents — AI agents that can be triggered by AgentTask schedules