Copy jobs

A copy job keeps a folder of one file share in step with another: on a schedule, Restow writes the newest restore point of share A that passed its restore check into a folder of share B. Typical uses are a second site that should hold the current state of the projects share, or a standby share.

A copy job is not a backup

The target keeps no versions: it holds the newest state only, and in the mode Mirror it deletes files that the source no longer has. The interface labels every copy job, its runs and its target with Not a backup: no versions on the target. A copy job never counts as protection: its runs are counted as restores, and a share that is only the source or target of a copy job is still “in no backup job”. Back the share up with a backup job as well.

Copy jobs are part of every edition, from 0.4.0. Like the rest of file share backup, they were tested against Samba only, see Troubleshooting and limits.

Set up a copy job

1. The target must allow restores. On the target share, switch on Allow restore to this share under Settings. Only shares with that switch can be a target. See Restore and restore checks.

2. Open Servers & clients → File shares and choose Copy jobs (the list “Copy jobs” on the Jobs page), then New job: the editor New copy job opens. You can also start from the restore dialog: under Another file share, Repeat on a schedule as a copy job fills in source, target and folder.

3. Fill in the editor:

   Field	What it means
   Name	Shown in the list, on the file share pages and in alerts.
   Copy from	The source share.
   Copy into	The target share. The source is not offered, and neither is a share that does not allow restores.
   Target folder	A folder relative to the root of the target. It is created when it does not exist. You can type it or choose it with Browse. A mirror needs a folder: it is never written into the root of a share.
   How to copy	Overwrite or Mirror, see below.
   Copy the permissions	Off by default. Only useful when both file servers know the same accounts.
   Verify written files	Reads every file back after writing. Slower; on by default for NFS targets.
   Schedule	As for a backup job: every day, every few hours, or cron. At most once an hour. Without a schedule the job runs only when someone starts it (Start now, called Run now before 0.4.5).

The two modes

Mode	What happens in the target folder
Overwrite	Files of the source replace those with the same name when they differ. Nothing else in the target folder is touched: files that exist only in the target stay.
Mirror	The target folder becomes the same as the source. What the source does not have is deleted, inside the target folder only. Nothing above it is touched.

Overwrite adds and replaces. Mirror is the mode for an exact replica, and the only run in file share backup that deletes anything.

What a run copies

• The source is the newest restore point whose restore check passed. The job picks it when the run starts, not when it is queued. A restore point counts when its restore check read back its sample files and found them intact (also when its backup ended With warnings). A restore point without samples does not count, see Restore checks. The target therefore lags the source by at least one backup and one restore check.
• When that restore point is the one the job copied last, the run ends at once with Nothing changed (“Already up to date”). Start now with Copy anyway copies again.
• When the source has no checked restore point yet, the run fails with share.copy_no_verified_point (“No checked restore point to copy yet”). Wait for the restore check, or start it on the source share (Run a restore check now).
• A run is a restore run: it needs the mounter, holds the target share like any restore (one run per share at a time), and appears under Runs of both shares with the kind Copy, and in History as a restore.

The safety rules for a mirror

A mirror deletes, so Restow checks six rules when you save the job and again when the run starts and in the runner, because settings can change in between:

1. The target allows restores. Otherwise share.restore_not_allowed.
2. Source and target are different places. The same share, or the same server, share and overlapping folders under another name, count as the same: share.copy_unsafe_target (“A copy never writes into the file share it copies”).
3. Never into the root of a share. The target folder needs at least one segment.
4. A folder that Restow did not create needs your confirmation. On its first run a mirror writes a marker file, .restow-copy.json, into the target folder. A later mirror run refuses a folder that is not empty and has no marker of this job, and a folder that carries the marker of another copy job, unless you confirmed it. When you save a mirror into a folder that exists and is not empty, the editor shows how many entries it holds (“A mirror deletes everything in it that is not in the source.”) and asks you to type the folder name (Mirror into this folder). Changing the target clears the confirmation. The marker is never deleted by the mirror itself; leave it in place.
5. An empty restore point is never mirrored (share.copy_empty_source): an emptied source must never empty the replica. This holds also with Copy anyway.
6. A restore point with fewer than half the files of the one copied last is not mirrored (share.copy_empty_source, “Mirror copy refused: the source looks emptied”). People do clean up, but this is also what a damaged or emptied source looks like. If the smaller state is intended, open the job and choose Copy anyway (“Copy {name} anyway?”). That copies this once and deletes the files the source no longer has.

Overwrite mode does not delete and does not check the number of files. Rules 1 to 3 apply to it as well.

Failures

Cause	Meaning
share.copy_no_verified_point	The source has no restore point with a passed restore check yet.
share.copy_unsafe_target	The target breaks a rule: the same place, the root of a share for a mirror, a folder that belongs to another copy job, or a non-empty folder nobody confirmed. The message names which. Nothing was copied.
share.copy_empty_source	A mirror refused an empty restore point or one with fewer than half the files of the last copy.
share.restore_not_allowed	The target share does not allow restores.
share.restore_partial	Some files could not be written: a name the target cannot hold, missing rights, no space. The run ends With warnings.

A retired share cannot be copied from or into: retiring a share switches off the copy jobs that read from it or write into it. Deleting a share deletes its copy jobs.

Notifications

A copy run raises Restore failed when it fails and Restore completed when something was copied (not for Nothing changed), with the copy job as the subject. Choose where they go in the notification matrix, see Notifications and reports.