Snapshot Schedules
A Snapshot Schedule takes point-in-time snapshots of a chosen set of Storage Volumes and Network Shares on a repeating schedule, and rotates them so each volume and share keeps a moving window of recovery points. Snapshots are space-efficient and instant, so a schedule that runs every few hours costs little more than the data that changes between runs.
A schedule keeps two kinds of snapshot: a small set of short term snapshots that follow the schedule directly, and an optional set of long term snapshots promoted out of them and held for hours, days, weeks, months or quarters. This page owns that retention model; Backup Policies and Remote-replication (DR) present the same controls for their own schedules and refer back here.
| Section | Covers |
|---|---|
| What a Run Does | The sequence of a single schedule run, snapshot naming, and what gets skipped |
| Creating a Snapshot Schedule | Every tab of the Create dialog, field by field |
| How Retention Works | Short term rotation, long term promotion, retention tags and expiration dates |
| Keeping a Snapshot Beyond Its Retention Window | Holds, and what renaming a snapshot does |
| Changing Which Volumes and Shares a Schedule Covers | The Update Selections dialog and the CLI add/remove commands |
| Modifying a Schedule | What the Modify dialog can and cannot change |
| Enabling, Disabling and Triggering | Suspending a schedule, and running one on demand |
| Reclaiming Orphaned Snapshots | Adopting snapshots left behind by a deleted schedule |
| Deleting a Schedule | What happens to the snapshots it created |
| Managing Snapshot Schedules from the CLI | The equivalent qs commands
|
| Troubleshooting | Snapshots not appearing, snapshots not expiring, pool filling up |
The Snapshot Schedule toolbar group holds four buttons -- Create, Modify, Delete and Update Selections -- and the Snapshot Schedules tab in the center pane lists the schedules with their status, scheduled hours, days, and short-term snapshot count.
Enable, Disable and Trigger are not on the toolbar. Right-click a schedule in the grid to reach them.
You can also start a schedule from the object it will cover: right-click a Storage Volume or a Network Share and choose Create Snapshot Schedule.
What a Run Does
Each time a schedule fires it works through the same sequence:
- Existing snapshots of each member are examined, long-term retention rules are applied, and any snapshot that is now surplus is queued for deletion. This runs as a Delete Storage Volume Schedule Expired Snapshot(s) or Delete Network Share Schedule Expired Snapshot(s) task, so expiry is visible in the Tasks pane.
/var/opt/osnexus/custom/schedule-prestart.shis run if it exists, with--name=<schedule name> --id=<schedule id>. See Custom scripts below.- New snapshots are created for every member that was not skipped.
All ZFS members that live in the same Storage Pool are snapshotted by a single ZFS command, so they share one point in time. That matters when a database or an application spans several volumes or shares in a pool: the set is crash-consistent with itself rather than seconds apart. Disable Atomicity on the Advanced Settings tab breaks that guarantee up into batches, and is only worth using on very large schedules -- see below.
Snapshot naming
Snapshot names are derived from the UTC time the run started, not local time:
| Member | Snapshot name |
|---|---|
| Network Share | <share>@GMT-2026.09.03-04.19.59
|
| Storage Volume | <volume>_GMT20260903_041959
|
The @GMT- form is the name Windows expects for Previous Versions, which is why share snapshots use it. Both forms are what the schedule looks for when it decides which snapshots it owns, so they are worth recognising in the snapshot list.
What a run skips
- Members owned by another appliance. A schedule object is visible grid-wide, but a run only snapshots the volumes and shares owned by the appliance the schedule runs on. Members that belong to another grid member are skipped.
- Members used by another schedule in the last 10 seconds. If a volume or share was snapshotted by any snapshot or replication schedule within the previous 10 seconds it is left out of this run and an alert is raised naming the resource and the schedule. Two schedules covering the same object at the same hour will interfere with each other this way, so stagger them with Offset.
- Demoted shares. A share whose name carries
_demoted_or_demotedclone_-- the result of promoting a snapshot -- is skipped, with an alert raised at most once a day. - A run that overlaps the previous one. A scheduled run is skipped rather than queued while work from the previous run for the same schedule is still active.
- Everything, if the schedule is disabled. A disabled schedule neither creates snapshots nor expires them.
A schedule that has no volumes and no shares left disables itself the next time it runs.
Creating a Snapshot Schedule
The dialog is a five-tab wizard; Next and Previous walk the tabs and OK is accepted from any of them. The dialog refuses to open at all if the grid has no storage volumes and no network shares.
General
- Schedule Name -- pre-filled with the next free
snapshot-sched-N. Names may contain letters, digits and the characters- _ .only, and must be unique across the grid. - Description -- free text, optional.
- Start date -- defaults to today. A calendar schedule ignores any trigger point earlier than this date, so set it forward to arm a schedule ahead of time.
- Enabled -- on by default. Clear it to create the schedule without arming it.
The Snapshot Schedules grid has a Resource Group column, but there is no resource group control on this dialog; assign one with the CLI's --resource-group argument.
Schedule Interval
Schedule Type picks between two mutually exclusive models, and the fieldset for the one you did not pick is greyed out:
- Use day/hour selections (default) -- a calendar schedule. Tick the days and the hours; the schedule runs at each ticked hour on each ticked day. The default is Monday through Friday at 12 AM, 4 AM, 8 AM, 12 PM, 4 PM and 8 PM. All Days and All Hours toggle every checkbox in their row at once.
- Use timer interval -- a rest interval instead of fixed times. The next run starts the given number of minutes after the previous run finishes, so runs cannot overlap and the effective period is the interval plus however long a run takes. The minimum is 3 minutes and a smaller value is reset to 3; the field defaults to 30 and the slider covers 3 to 360 minutes.
Offset
Offset shifts every calendar trigger point by 0 to 59 minutes past the hour. It is the control to reach for when several schedules, or a schedule and a replication schedule, would otherwise fire on the same hour and skip each other's members: give each one a different offset and they no longer collide.
The hour checkboxes relabel themselves to the offset minute as you move the slider, so the tab always shows the times the schedule will actually run.
Offset applies to calendar schedules only; it has no effect on a timer interval schedule.
Two inner tabs, Network Shares and Storage Volumes, each hold a dual list: available objects on the left, the schedule's members on the right, moved with the arrow buttons or by dragging. At least one volume or share must be selected or OK is refused.
Each list has its own filter bar:
- the Storage Pool combo narrows the list to one pool;
- the text field takes one or more comma-separated terms and matches them against the object name -- prefix a term with
pool:to filter by pool name or ID instead, for examplepool:pool-1,pool:pool-2; - Search applies the filter and Reset clears both the text and the pool selection.
Hide Nested Shares, on the Network Shares tab, is ticked by default and hides nested shares so the list shows only top-level shares.
What the lists offer is deliberately narrow:
- Network Shares -- ZFS and CephFS shares only. Cloud shares, share aliases and sub-shares are not listed and cannot be added to a schedule.
- Storage Volumes -- volumes that are not themselves snapshots and are not cloud-backup volumes.
- Snapshots already created by a schedule are excluded from both lists, so you cannot build a schedule that snapshots another schedule's output by accident.
A volume or share may belong to several schedules at once -- for instance an hourly schedule for a short window and a daily schedule holding a longer history. Each schedule counts and expires only the snapshots it created itself.
Snapshot Settings
- Long Term Snapshot Retention Settings -- how many hourly, daily, weekly, monthly and quarterly recovery points to hold. Each field defaults to 2 and accepts up to 1000. Suggested Defaults puts all five back to 2, and Clear sets all five to 0, turning long-term retention off.
- Max Short Term Snapshots -- how many schedule-driven snapshots to keep in the rotating window. The default is 3; the service limit is 1000.
- Max Total Source Snapshots -- the sum of the five long-term counts and Max Short Term Snapshots, recomputed as you type. It is the ceiling on how many snapshots of one member this schedule will hold, and the number to sanity-check against pool free space before you commit.
Long-term retention applies to ZFS and CephFS members, which is every member a schedule can have.
Advanced Settings
- Recursively snapshot nested shares -- snapshots each selected share together with the shares nested beneath it, in the same operation. It has no effect on storage volumes.
- Reclaim Orphaned Snapshots -- adopts snapshots that another schedule created, so this schedule counts and expires them. See Reclaiming Orphaned Snapshots.
- Disable Atomicity -- snapshots the members in batches rather than as one transaction per pool. A single transaction covering hundreds of datasets is a long transaction; batching keeps each one short at the cost of the members no longer sharing an identical point in time. The batch size is 16 by default and is set with
non_atomic_snapshot_batch_sizein the[schedule_manager]section of/etc/quantastor.conf. - Force -- lets you add a replication checkpoint to the schedule. Without it, selecting a checkpoint object is refused, because the next run of the replication schedule that owns the checkpoint will delete any snapshot taken of it. Force exists for the cases where that is acceptable; it is on the Create dialog only.
How Retention Works
Both retention mechanisms act only on snapshots this schedule created, identified by the schedule ID stamped on each snapshot when it was taken.
Short term retention is the rotating window. After each run the schedule counts the snapshots it owns and marks the oldest surplus ones for deletion until only Max Short Term Snapshots untagged snapshots remain.
Long term retention does not create anything. After each run the schedule sorts the snapshots it owns oldest to newest and, for each of the five rules independently, keeps the oldest one and then the next one that is at least the rule's spacing later, up to the count you configured; when it has more than the count it drops the oldest one it was holding. Snapshots picked by any rule are tagged and are then exempt from the rotating window.
| Rule | Minimum spacing between kept snapshots | A count of 4 gives you |
|---|---|---|
| Hourly | 1 hour | 4 snapshots spanning the last 4 hours |
| Daily | 1 day | 4 snapshots spanning the last 4 days |
| Weekly | 7 days | 4 snapshots spanning the last month |
| Monthly | 30 days | 4 snapshots spanning the last 4 months |
| Quarterly | 90 days | 4 snapshots spanning the last year |
Spacing is matched with a five-minute tolerance, so a schedule that drifts slightly still satisfies a rule.
The practical consequence is that long-term retention can only promote a snapshot that the schedule already took. A quarterly count of 4 on a schedule that only ran for a week gives you one tagged snapshot, not four -- the other three slots have nothing to promote. Set the calendar or interval so that a snapshot exists at roughly the spacing each rule needs.
Retention tags and expiration dates
Each snapshot carries the tags it earned and a projected expiration date, both shown in the snapshot list under its parent volume or share.
- Schedule -- the schedule that created the snapshot. A raw GUID shown in red means the schedule no longer exists, so nothing is rotating that snapshot any more.
- Retention Tags --
deltafor a snapshot held by the rotating window, andhourly,daily,weekly,monthlyorquarterlyfor each long-term rule holding it. A snapshot commonly carries several. A snapshot with no tags at all is the next one out. - Expiration -- the date the longest-held tag stops covering the snapshot, computed from its creation time.
N/Ameans no long-term tag applies. It is a projection for planning, not a timer: the snapshot is removed when a run finds it surplus, not when this date passes.
The window each tag projects is the retention count multiplied by the rule's period, so 2 quarterlies gives a snapshot roughly 269 days.
Keeping a Snapshot Beyond Its Retention Window
Two mechanisms take a snapshot out of a schedule's reach. They behave differently, and only one of them works for both object types.
Put a hold on it. A snapshot with at least one hold is excluded from schedule cleanup entirely -- it is not counted and not deleted, whatever the retention settings say -- and it also cannot be deleted by hand until the hold is released. This is the reliable option, and the only one that works for share snapshots.
qs share-hold-add --share=<share snapshot> --hold-tag=keep-for-audit qs volume-hold-add --volume=<volume snapshot> --hold-tag=keep-for-audit
Use qs share-hold-remove and qs volume-hold-remove to release one, and qs share-list --snapshots-with-holds-only=true or qs volume-list --snapshots-with-holds-only=true to list what is currently held. The web interface offers the same operations as Add Hold and Remove Hold on a snapshot.
Rename it -- storage volume snapshots only. Renaming a storage volume snapshot clears its schedule ownership, so the schedule stops counting it and will never expire it. The snapshot survives indefinitely and is yours to delete. Renaming a share snapshot does not do this: the QuantaStor object is renamed but the underlying ZFS snapshot name and the schedule ownership are unchanged, so the schedule still owns it. Use a hold for shares.
Setting a description on a snapshot does not protect it.
Membership is not on the Modify dialog. Update Selections is the only dialog that changes it, and the same dialog is what the Update Selections right-click item opens -- it is titled Update Selections for Snapshot Schedule and was called Add/Remove Volumes in earlier releases.
Pick the schedule at the top and the two dual lists load with its current members already on the right. What you leave on the right when you click OK becomes the membership -- the dialog replaces the whole set rather than adding to it, so anything you move back to the left is removed from the schedule. As on the Create dialog, at least one volume or share must remain selected.
Two details differ from the Create dialog:
- Hide Nested Shares starts unticked if the schedule already contains a nested share, so its existing members are visible.
- The Storage Volumes list is restricted to ZFS and Ceph RBD volumes.
Removing a member from a schedule does not delete the snapshots it already has; they stay, and stop being rotated. From the CLI, qs snap-schedule-add and qs snap-schedule-remove change membership incrementally instead of replacing it:
qs snap-schedule-add --schedule=nightly --volume-list=vol3,vol4 qs snap-schedule-remove --schedule=nightly --share-list=share2 qs snap-schedule-assoc-list --schedule=nightly
Modifying a Schedule
The Modify dialog carries the same General, Schedule Interval, Snapshot Settings and Advanced Settings tabs as Create, with a schedule chooser at the top of the General tab. There is no Select Volumes & Shares tab and no Force checkbox, and the Advanced Settings tab gains Old Schedule ID.
Reducing Max Short Term Snapshots or clearing the long-term counts takes effect on the next run, which will delete whatever is now surplus. Changing the schedule type, days, hours, interval or offset re-plans the schedule immediately.
Enabling, Disabling and Triggering
Each of the three dialogs is a single schedule chooser. The Trigger dialog also shows a Schedule Information panel with the schedule's state and its storage volume and network share counts, so you can confirm you picked the right one before running it.
Disabling a schedule stops both halves of its work: no new snapshots and no expiry. Existing snapshots are untouched and start accumulating no further, which makes disable the safe way to freeze a history in place while you investigate something. Enabling it again resumes both.
Triggering runs the schedule immediately, in addition to its scheduled runs, and the snapshots it creates count against the retention settings like any others. Triggering a disabled schedule does nothing at all -- enable it first.
qs snap-schedule-disable --schedule=nightly qs snap-schedule-enable --schedule=nightly qs snap-schedule-trigger --schedule=nightly
Reclaiming Orphaned Snapshots
Delete a schedule and its snapshots stay behind with its ID still stamped on them. Nothing rotates them any more, and they show that ID as a red GUID in the Schedule column of the snapshot list. On a busy share those orphans accumulate and consume pool space indefinitely.
Reclaim Orphaned Snapshots, on the Advanced Settings tab of both the Create and Modify dialogs, hands them to the schedule you are creating or modifying. When you click OK, each of the schedule's volumes and shares is scanned for snapshots that are stamped with some other schedule's ID, and each one found is re-stamped with this schedule's ID -- in the database and in the quantastor:scheduleid and quantastor:scheduletype properties on the dataset itself. From then on they are counted by this schedule's retention rules and rotated out by it like its own snapshots.
Two limits are worth knowing:
- Only snapshots taken by a snapshot schedule or by hand are adopted. Snapshots created by a replication schedule or a backup policy are left alone, so reclaiming cannot break a replication relationship.
- The scan covers the schedule's own members only. Add the volumes and shares whose orphans you want adopted before you tick the box.
Old Schedule ID, on the Modify dialog, narrows the scan from "any other schedule" to one specific schedule. It stays greyed out until Reclaim Orphaned Snapshots is ticked, and the value must be a UUID. Use it when a share carries orphans from more than one retired schedule and you only want one set adopted -- the red GUID in the snapshot list is the value to paste in.
Deleting a Schedule
Deleting a schedule removes the schedule object only. Every snapshot it created remains, and nothing expires them from that point on -- they become the orphans described above. If you are replacing a schedule rather than retiring it, create the replacement with Reclaim Orphaned Snapshots ticked so the existing history keeps rotating.
Custom scripts
Scripts placed in /var/opt/osnexus/custom/ are run at fixed points if they exist. Snapshot schedules use one:
| Script | When it runs |
|---|---|
schedule-prestart.sh |
At the start of every schedule run, before any snapshot is taken |
Each hook has two forms. schedule-prestart.sh runs synchronously and blocks the run until it exits, under a five-minute timeout; schedule-prestart-async.sh is backgrounded and nothing waits for it. Both are called with --name=<schedule name> --id=<schedule id>, so one script can serve every schedule and branch on the name.
Where the Snapshots Appear
Schedule-created snapshots are listed under the volume or share they were taken from, not under the schedule. In the web interface, expand a Network Share or Storage Volume in the tree, or select it and use the Snapshots tab in its detail panel.
From the CLI, share snapshots have to be asked for explicitly, while volume snapshots are always included:
qs share-list --include-snapshots=true qs volume-list
Recovering data out of a snapshot -- browsing it over NFS or SMB, restoring, rolling back or cloning it -- is covered on Network Shares and Storage Volumes.
Managing Snapshot Schedules from the CLI
| Command | Alias | Purpose |
|---|---|---|
snap-schedule-create |
sch-create |
Create a schedule |
snap-schedule-modify |
sch-modify |
Change a schedule's settings |
snap-schedule-delete |
sch-delete |
Delete a schedule; its snapshots are kept |
snap-schedule-enable |
sch-enable |
Enable a schedule |
snap-schedule-disable |
sch-disable |
Disable a schedule |
snap-schedule-trigger |
sch-trigger |
Run a schedule now |
snap-schedule-list |
sch-list |
List all schedules |
snap-schedule-get |
sch-get |
Show one schedule in full |
snap-schedule-add |
sch-add |
Add volumes or shares to a schedule |
snap-schedule-remove |
sch-remove |
Remove volumes or shares from a schedule |
snap-schedule-assoc-list |
scha-list |
List a schedule's members |
A calendar schedule, weekdays at 2 AM and 6 PM, thirty minutes past the hour, keeping four rotating snapshots plus a week of dailies and a month of weeklies:
qs snap-schedule-create --name=nightly \ --days=mon,tue,wed,thu,fri --hours=2am,6pm --offset-minutes=30 \ --volume-list=vol1,vol2 --share-list=share1 \ --max-snaps=4 --rc-dailies=7 --rc-weeklies=4
An interval schedule that snapshots one share every 30 minutes and keeps the last twelve:
qs snap-schedule-create --name=frequent \ --schedule-type=interval --interval=30 \ --share-list=share1 --max-snaps=12
Adopting the orphans on a share into an existing schedule:
qs snap-schedule-modify --schedule=nightly --reclaim-old-snapshots=true
Arguments worth knowing: --schedule-type takes calendar or interval; --enabled takes true or false; --include-nested-shares, --disable-atomicity and --reclaim-old-snapshots are the CLI names for the Advanced Settings checkboxes; and --resource-group assigns a resource group, which the dialogs do not offer.
Troubleshooting
No snapshots are being created
- Check the schedule is enabled --
qs snap-schedule-get --schedule=<name>reports Is Enabled. A schedule left with no members disables itself, so an unexpectedly disabled schedule is often an empty one. - Check it still has members --
qs snap-schedule-assoc-list --schedule=<name>. - Check the members are owned by this appliance. A schedule run skips volumes and shares that belong to another grid member.
- Check for a collision. If another snapshot or replication schedule covers the same objects on the same hour, one of them will find its members busy and skip them; the alert names the resource and the schedule. Separate them with Offset.
- Check the pool has free space. A snapshot of a full pool cannot be created.
- The service log records every trigger decision:
journalctl -u quantastor --since "1 hour ago" | grep -i sched.
Snapshots are not being expired
- Check Retention Tags on the snapshot. A long-term tag exempts it from the rotating window until its rule stops holding it.
- Check for a hold. A held snapshot is excluded from schedule cleanup entirely;
qs share-list --snapshots-with-holds-only=truelists the held share snapshots. - Check whether the snapshot has snapshots or clones of its own. A snapshot with children is never auto-deleted; remove the child first.
- Check the Schedule column. A red GUID means the owning schedule was deleted and nothing is rotating that snapshot -- see Reclaiming Orphaned Snapshots.
- For a storage volume snapshot, check it has not been renamed. Renaming clears schedule ownership by design.
The pool is filling up with snapshots
A snapshot holds on to the blocks that have been overwritten since it was taken, so cost tracks write volume, not the size of the data. Work down from Max Total Source Snapshots: it is the number of snapshots of each member the schedule will hold at once, and the honest input to a capacity estimate.
- Reduce Max Short Term Snapshots, or Clear the long-term counts you are not using.
- Lengthen the interval, or drop hours from the calendar selection.
- Release holds on snapshots you no longer need to keep.
- Watch the Snapshot Used figure per share and volume, and set capacity alerts on the pool -- see Storage Pools.
Related pages
- Storage Volumes -- provisioning volumes, and browsing, cloning and reverting their snapshots
- Network Shares -- provisioning shares, nested shares, and snapshot access over NFS and SMB
- Storage Pools -- the pool the snapshots consume space from
- Backup Policies -- file-level backup to and from a remote export, with the same schedule and retention controls
- Remote-replication (DR) -- replicating volumes and shares to another QuantaStor system on a schedule
Verified against QuantaStor 6.9.0.