File shares: overview and requirements

Restow backs up an SMB share (a share of a Windows Server, Samba or a NAS) or an NFS export from the server side. There is no agent on the file server: Restow mounts the share read-only for the length of one run, reads it with restic, and writes the result into a repository of its own. A restore can go to a ZIP download, a new folder, the original location or another share, with the NTFS permissions put back where the target allows it.

The web interface calls a share a file share (German: Freigabe). You find the feature under Servers & clients → File shares.

How it works

A backup job of the kind File shares starts a run on its schedule (or you choose Back up now on the share).
The mounter (see below) creates a temporary Docker volume that mounts the share through the kernel of the Docker host, and starts a short-lived runner container from the running Restow image with that volume, read-only.
The runner walks the share, records the permissions of every file and folder, and backs up the data with restic into the share’s own repository, file-shares/<share id>/ in the tenant’s primary repository. The runner reaches only the api, through the internal runners network of the Compose project, with a credential that is valid for this one run and can only add data.
When the run ends, the container and the volume are removed. The password of the share exists in the volume’s options only while the run lasts.

Adding, testing, browsing, backing up or restoring a share never restarts the api or the worker. That is the difference to NFS as backup storage (see Mounter and NFS storage), and the reason why tenant administrators can add their own file shares.

What a restore point holds

Files and folders with their sizes and modification times, as the server presented them. Symbolic links are kept as links where the server shows them.
Permissions. On SMB the owner, group and the access control list of every file and folder (the auditing entries as well, when the account may read them), stored next to the data inside the same restore point. NFSv4 and POSIX ACLs of an NFS export are kept as well, on a best-effort basis. The share’s option Back up the permissions is on by default.
What is not kept: alternate data streams (the Linux SMB client does not show them), access times, and a consistent state across files. Files are read one after another while people work, see Troubleshooting and limits.

A file that is open with an exclusive lock, cannot be read, or exists only as an offline placeholder is skipped. The run then ends With warnings, and the files are listed in the run with the cause. A run that ends with warnings is a complete restore point of everything that could be read.

Requirements

The mounter

File share backup runs in containers that the mounter starts. The mounter is a small container next to Restow, in the Compose profile mounts, and it holds the Docker socket, which is root access to the Docker host. Read Mounter and NFS storage before you start it.

New installations start it by default. Since 0.4.0 install.sh starts the mounter together with the stack. --no-mounter (or its alias --without-mounter) leaves it off. Running the installer again on an existing installation keeps that installation’s choice.
Existing installations start it once. The provider owner chooses Enable network shares (under Installation → Default repository & network shares, or in the notice on the File shares pages) when the opt-in updater runs. The button needs a recent sign-in and is recorded in the audit log. Without the updater, run this in the directory with docker-compose.yml:
Terminal window
```
docker compose --profile mounts up -d mounter
```
While it is off, the File shares pages say so, and scheduled backups of shares wait. A run that cannot start shows the cause share.mounter_unavailable.
A compose file of 0.4.0 or newer. An installation that was updated from 0.3.6 keeps its old docker-compose.yml, which has no runners network. The mounter then reports runner_network_missing, and file share runs cannot start. Run the install.sh of 0.4.0 or newer again in the installation directory, see Running it again.

The Docker host

The Docker daemon mounts the share with the kernel of the Docker host, not with tools inside a container.

Protocol	What the host kernel needs	If it is missing
SMB	The `cifs` module: `modprobe cifs`. On Ubuntu cloud kernels it is in the package `linux-modules-extra-$(uname -r)`.	The test fails with `share.client_missing`.
NFS	The NFS client: `nfs-common` (Debian, Ubuntu) or `nfs-utils` (RHEL family).	The same cause, `share.client_missing`.

Make the module load at boot (for example with a file in /etc/modules-load.d/), so that a reboot does not stop the backups. On an arm64 host the kernel needs the cifs module as well.

SELinux. On a host with SELinux enforcing, a container cannot read a cifs or nfs mount without a context= option. The mounter adds it when its environment has RESTOW_MOUNTER_SELINUX_CONTEXT=true (the default is false). The mounter service of the release docker-compose.yml passes only a fixed list of variables, so a line in .env alone does not reach it: put the variable into the mounter service in docker-compose.override.yml, then recreate the mounter.

services:
  mounter:
    environment:
      RESTOW_MOUNTER_SELINUX_CONTEXT: "true"

docker compose --profile mounts up -d mounter

This was not tested on a host with SELinux enforcing. The sign is a test that mounts but then reads “Permission denied”.

Network and ports

It is the Docker host, not a container, that must reach the file server:

Protocol	Ports from the Docker host to the file server
SMB	TCP 445
NFS	TCP 2049. NFSv3 also needs the portmapper (111) and the mount daemon.

The runners have no network of their own beside the internal runners network to the api: they cannot reach the database, the internet or the file server directly. For the other ports of Restow see Network and ports.

A file server on a private or loopback address (most file servers are) is added by a provider administrator at any time. A tenant administrator needs a provider administrator’s approval of that share, or an installation switch, see Budgets, networks and runners.

The SMB account

Restow signs in with one account and a password. A domain account or a local account of the file server both work.

Read access to everything that should be backed up. Best is a member of Backup Operators (Windows) or an account with SeBackupPrivilege (Samba: sec privileges). Such an account reads files whose access control list would deny it, and it can read their permissions.
For restores into the share: write access. To put the permissions back it also needs SeRestorePrivilege (owners) and SeSecurityPrivilege (auditing entries). Without them a restore still writes the content, and the run ends with the warning share.acl_partial.
SMB versions: 2.1 to 3.1.1. The add dialog offers 3.1.1 (recommended), 3.0 and 2.1 (“outdated, no encryption”). SMB 1 and NTLMv1 are refused. Kerberos is not supported: the account signs in with NTLMv2.
Encryption (Encrypt the connection) needs SMB 3. It is off by default, because many NAS devices are slow with it. Turn it on when the traffic leaves your own network.

NFS exports

The export must allow the address of the Docker host.
root_squash (the default) makes the runner read as nobody. Files that only root may read are then skipped with a warning. For a complete backup, export with no_root_squash, or make the files readable.
Versions 3, 4, 4.1 and 4.2. The authentication is by host (AUTH_SYS), as for NFS storage.

Who can use it

The file share pages are for tenant administrators, who manage the shares of their own tenant, and for provider administrators working in a tenant. As for machines, a member of the provider team with a read-only role sees that backups happened but cannot browse or restore their content. Tenant users and restore operators have no file share pages in 0.4.7: there is no self-service restore of shares for them. Budgets and the private-network approval are for provider administrators only.

Where file shares show up

A share in an enabled backup job counts as protected, and it is counted next to mailboxes, machines and VMs:

Status tab and start page. The last successful backup of the type File shares, the number of protected objects (including file shares), and the notice “N file shares in no backup job” with Open file shares.
Recovery readiness. One row per share, rated by the restore check of its newest restore point, see Restore and restore checks and Restore readiness.
Warnings. A backup that ended with warnings is listed on the Warnings page and can be acknowledged like any other.
History and statistics. Backup, restore and copy runs appear in History, linked to the share. The statistics count the readiness, the backup outcomes, the restores and the data added. A copy run counts as a restore, never as protection.
Provider view. It reports fileShares, fileSharesWithoutJob and fileSharesFailed, with the hints file_share_backup_failed and file_shares_without_job.

Notifications and the API

Events. A failed run raises Backup failed (also for a refused password, so that a changed password reaches someone the same night), a share without a successful backup raises Backup overdue (backup.overdue), restores raise Restore failed and Restore completed, restore checks raise the Restore check events. Two events are specific to shares: Storage budget of file shares (file_share.storage_quota) and Backup data of a file share stays locked (file_share.repository_locked). Choose where they go in the notification matrix, see Notifications and reports.
Scheduled reports have no block of their own for file shares in 0.4.7. The release notes of 0.4.0 list this as a known issue. File shares are part of the figures of the statistics that a report quotes, such as the backup success rate and the share proven restorable.
API. GET /api/v1/status carries fileShares (the counts of file shares) and, in the readiness summary, sharesWithoutJob. This came with the integration API contract 1.4.0 and is additive. See Integration API.