Add a share and back it up

Before you start, check the requirements: the mounter runs, the Docker host has the cifs module or the NFS client, and the Docker host reaches the file server. Without the mounter the pages say so, and scheduled backups of shares wait. A tenant administrator sees “This installation does not back up file shares yet. Your provider can switch it on.”; the provider owner sees Enable network shares.

Who adds shares. Tenant administrators manage the shares of their own tenant. Provider administrators do the same in a tenant. A file server on a private or loopback address needs more, see Budgets, networks and runners: a provider administrator may always add it, a tenant administrator only with an approval or an installation switch.

Open Servers & clients → File shares and choose Add file share. The dialog has four steps: Protocol, Connection, Test and Options.

Protocol. SMB (Windows, Samba, NAS) or NFS.

Connection. The fields:

Field	What to enter
Server	A host name or an IP address, without `\\` or `smb://`.
Share (SMB) or Export (NFS)	The name of the share, for example `Projects` (at most 80 characters, none of `\ / : * ? " < > \|`), or the exported path, for example `/volume1/data`.
Subfolder	Optional. Back up only this folder of the share. The container then sees only that folder.
Account and Domain (SMB)	`backup`, `DOMAIN\backup` or `backup@corp.example.com`. The domain can also go into its own field. The account cannot contain `,`, `=` or `/`.
Password (SMB)	At most 256 bytes, no control characters. A password with a part between commas that equals a mount option (such as `ro` or `exec`) is refused.
SMB version	3.1.1 (recommended), 3.0, or 2.1 (outdated, no encryption). A share on 2.1 shows “SMB 2.1: outdated”.
Encrypt the connection (SMB)	SMB 3 encryption. Off by default, because many NAS devices are slow with it. It needs SMB 3.
NFS version	3, 4, 4.1 or 4.2. NFS 4.1 is the default.

Test. Choose Test connection. The test mounts the share once, reads its top folder and unmounts it. It shows the Top-level folders (and Use as subfolder next to each, if you want to back up only one) and what the account can read of the permissions:

Result	Meaning
“Owner, permissions and auditing entries can be read.”	Complete.
“Owner and permissions can be read.”	The account cannot read the auditing entries. Backups hold the owner and the access control list.
“Permissions only: the owner cannot be read with this account.”	The account lacks the right to read the owner.
“NFS permissions can be read.”	NFS: the permissions of the export can be read.
“Permissions cannot be read with this account. Files are backed up without them.”	Add the account to Backup Operators, see the SMB account.

A failed test names the cause and the first step, for example “The file server refused the account”. The causes are in Troubleshooting and limits.

You can save without a passed test, for example when the server is down tonight. Restow asks once (“Save without a passed test”).

Options. A Name (shown in the list, in jobs and in alerts; unique among the tenant’s shares), and two switches:
- Back up the permissions (on). Stores the NTFS or NFS permissions of every file and folder, so that a restore can put them back.
- Allow restore to this share (off). While it is off, restores and copy jobs cannot write into this share. Restoring into the original share is the case where a restore overwrites files, which is why it is off until you decide otherwise. A ZIP download always works. See Restore and restore checks.

Choose Save file share. The dialog then asks Which job backs it up?. A file share without a job is not backed up. Choose Add to job (an existing file share job, with the folders), New job, or Later.

The password

The password is sealed with the tenant key and never shown again: the API reports only that a password exists. To change it, open the share’s Settings tab, Connection, enter a New password and save (“Empty keeps the stored password”). The share does not have to be added again. When the server refuses the password, the share’s Overview shows “The password was refused” with the time, and backups fail until a test or a run succeeds with the new one.

Changing the server, the share name, the export or the subfolder of a share that has restore points asks you to confirm (“Back up another place?”): the restore points of the old place stay, but the next backup reads everything again and counts as a first backup.

The backup job

A share is backed up by a backup job of the kind File shares. On the File shares page, Jobs opens the list “File share jobs”, and New job there opens the editor “New file share job”. A file share is in one job at a time; adding one that is in another job takes it over only after you confirm.

Section	What you set	Default
File shares	Which shares the job backs up, and per share which Folders: everything, or folders chosen from a live view of the share (Choose folders).	Everything
Schedule	Run on a schedule: Every day at a time, Every few hours, or a Cron expression (five fields), in a time zone. At most once an hour. Without a schedule the job runs only when someone starts it.	Daily
Retention	Daily restore points, Weekly restore points, Monthly restore points: how many restore points each share keeps.	30 daily, 12 weekly, 12 monthly
Exclusions	Skip temporary and system files (a preset, shown under the switch), Own patterns (one per line, for example `.bak` or `Archive/Old`), Leave out file types, Leave out files larger than* (size in GB).	The preset is on
Recall offline files	Files that were moved to slower storage (tiering, cloud sync) are left out unless this is on. Reading them brings them back to the server first.	Off
Reading and bandwidth	Upload limit (kbit/s) and time windows with another limit, and Parallel reads (1 to 16). The limit that applies when a run starts holds for that run. Empty parallel reads: the installation’s default, see Budgets, networks and runners.	No limit

The preset Skip temporary and system files leaves out ~$*, *.tmp, Thumbs.db, desktop.ini, .DS_Store, *.lck, $RECYCLE.BIN, System Volume Information, .snapshot, ~snapshot, #recycle, #snapshot, @eaDir and .@__thumb. The snapshot folders of NetApp, Synology and QNAP are in it on purpose: without them every server-side snapshot would be backed up again.

There is no separate restore check schedule: every new restore point is checked right after the backup, see Restore and restore checks.

What a run does

A scheduled run, or Back up now on the share, goes through these steps. The run’s page shows the phase.

Phase	What happens
Waiting	The run waits for a free runner, see runner settings. One run per share at a time.
Preparing	The mounter mounts the share read-only and the runner checks that it really is the mounted share. It refuses to back up an empty share when the last restore point was not empty, see An empty share.
Reading the folders	The runner walks the folders: it counts files and bytes, reads the permissions of every file (it reuses the previous ones for files that did not change) and notes what it must skip.
Backing up	restic reads the changed files and writes them into the share’s repository.
Finishing	The runner takes up to 20 sample files for the restore check and reports the result. The run ends as Completed, With warnings, Failed or Cancelled.

Every run makes a restore point, also when nothing changed, so that retention and the restore check see every successful run. A scheduled run that comes due while the previous backup of the same share is still waiting is not queued a second time: it is recorded as Cancelled with the note “Skipped: the previous run was still running”.

Cancel run on a running run stops it. A run longer than the longest run time (72 hours by default) is stopped as well, see runner settings.

Stopping a run

Since 0.4.2 a run of a file share can also be cancelled from the run drawer (the detail of a run in History), as the runs of Microsoft 365 and IMAP already could, besides Cancel run on the page of the share. It asks first, and the audit log records file_share.run_cancel_requested.

A run that waits for a free runner ends Cancelled without starting.
A running run gets the request with its next progress report (at most every 5 seconds). The runner stops restic with an interrupt and reports the run as Cancelled. A run that does not honour the request within two minutes is stopped by the server.
The end is “Cancelled”, not a failure. Nothing of the stopped run becomes a restore point, and the last good one stays the newest.
A whole job (since 0.4.5). Stop on a file share job in the job list withdraws its waiting runs and has the runners stop the running ones in one request; Start now (called Run now before 0.4.5) starts it by hand (Backup jobs).

Runs of Proxmox VE guests and of machines have their own Stop (Proxmox VE, servers and clients).

Warnings

A run that skipped files ends With warnings: the restore point holds everything that could be read, and the run lists the files with the cause. The warning appears on the Warnings page, where an administrator can acknowledge it like any other.

In the run	Cause	What to do
Locked by another program	`share.locked_files`: the file is open on the server with a lock.	Back up at night, when nobody has files open. There is no VSS over SMB.
Could not be read	`share.read_errors`: other per-file errors.	Read the message of the file. Often the account lacks the right.
Permissions could not be read	`share.acl_partial`: the account may not read the permissions of some files.	Put the account into Backup Operators.
Offline file left out	`share.offline_skipped`: a file that exists on the server only as a placeholder was skipped, as the job says.	Switch on Recall offline files if you want them.
Far fewer files than last time	`share.files_dropped`: the share holds fewer than half the files of the previous restore point. It was backed up as found.	Check whether files were deleted on purpose before retention removes the older restore points.

A run keeps the first 10,000 files it lists and counts the rest (“N more are counted but not listed”). The full list of causes, also for failed runs, is in Troubleshooting and limits.

Retention would delete good restore points if an empty backup replaced them. Restow therefore refuses to back up a share that is empty (or whose chosen folders are empty) when the previous restore point had files. The run fails with share.empty_source (“The share is empty”), nothing is backed up, and nothing is removed from the backups. Check the share: a wrong subfolder, a server that mounted the wrong volume, or a share that was really emptied. If it was emptied on purpose, choose Back up the empty share once on the share’s Overview (or on the failed run). It allows one empty backup, then the guard is back. share.include_missing is the same check for a folder of the job that no longer exists.

Choose a share in the list. The list shows its State (Protected, With warnings, Failed, Running, Overdue, In no job, No backup yet or Retired), the Restore check, the Last backup and the Job. The share page has the buttons Test connection and Back up now, and four tabs:

Overview. Protection (state, restore check, job and folders, last backup, number of restore points), live progress of a running run (phase, files and bytes, the current path), the repository size against the budget, and the connection with the last test.
Restore points. The restore points with their files and what each added, the file browser, search and the restore dialog, see Restore and restore checks.
Runs. Backups, restores and copies with status, duration, files, data added and warnings. A run opens a sheet with its files by cause, the explanation of a failure and its log.
Settings. The connection and the password, Read all permissions again (once, at the next backup; otherwise only changed files are read again), Allow restore to this share, the private network approval, the job and folders, the Budget, the copy jobs that read from or write into this share, the restic repository password, and the Retire or delete section.

The repository password

The share’s repository is a plain restic repository, file-shares/<share id>/ in the tenant’s primary repository. Its password is sealed in Restow. Show password in the settings reveals it after a confirmation, and the action is recorded in the audit log. You need it only to open the repository without this installation, for example after a disaster. Anyone with this password and access to the repository can read every backup of the share: keep it as carefully as the master key.

Stop, retire, delete

Retire stops the backups and keeps the restore points. A retired share is listed under “Show retired file shares”, and copy jobs that read from it or write into it are switched off. Reactivate takes it back.
Delete with all restore points removes the share and every restore point for good. It needs the share’s name typed and a recent sign-in, and it cannot be undone.
Taking a share out of its job does not delete anything. It is only no longer backed up.

For a repository that is locked by immutable backups, the deletion cannot free the data before its lock has run out, see Troubleshooting and limits.