Add options to fine tune VSS snapshots

changelog/unreleased/pull-3067

@@ -0,0 +1,22 @@
+Enhancement: Add options to configure Windows Shadow Copy Service
+
+Restic always used 120 seconds timeout and unconditionally created VSS snapshots
+for all volume mount points on disk. Now this behavior can be fine-tuned by
+new options, like exclude specific volumes and mount points or completely
+disable auto snapshotting of volume mount points.
+
+For example:
+
+    restic backup --use-fs-snapshot -o vss.timeout=5m -o vss.exclude-all-mount-points=true
+
+changes timeout to five minutes and disable snapshotting of mount points on all volumes, and
+
+    restic backup --use-fs-snapshot -o vss.exclude-volumes="d:\;c:\mnt\;\\?\Volume{e2e0315d-9066-4f97-8343-eb5659b35762}"
+
+excludes drive `d:`, mount point `c:\mnt` and specific volume from VSS snapshotting.
+
+    restic backup --use-fs-snapshot -o vss.provider={b5946137-7b9f-4925-af80-51abd60b20d5}
+
+uses 'Microsoft Software Shadow Copy provider 1.0' instead of the default provider.
+
+https://github.com/restic/restic/pull/3067

cmd/restic/cmd_backup.go

@@ -445,7 +445,16 @@ func findParentSnapshot(ctx context.Context, repo restic.ListerLoaderUnpacked, o
 }
 
 func runBackup(ctx context.Context, opts BackupOptions, gopts GlobalOptions, term *termstatus.Terminal, args []string) error {
-	err := opts.Check(gopts, args)
+	var vsscfg fs.VSSConfig
+	var err error
+
+	if runtime.GOOS == "windows" {
+		if vsscfg, err = fs.ParseVSSConfig(gopts.extended); err != nil {
+			return err
+		}
+	}
+
+	err = opts.Check(gopts, args)
 	if err != nil {
 		return err
 	}
@@ -547,8 +556,8 @@ func runBackup(ctx context.Context, opts BackupOptions, gopts GlobalOptions, ter
 			return err
 		}
 
-		errorHandler := func(item string, err error) error {
-			return progressReporter.Error(item, err)
+		errorHandler := func(item string, err error) {
+			_ = progressReporter.Error(item, err)
 		}
 
 		messageHandler := func(msg string, args ...interface{}) {
@@ -557,7 +566,7 @@ func runBackup(ctx context.Context, opts BackupOptions, gopts GlobalOptions, ter
 			}
 		}
 
-		localVss := fs.NewLocalVss(errorHandler, messageHandler)
+		localVss := fs.NewLocalVss(errorHandler, messageHandler, vsscfg)
 		defer localVss.DeleteSnapshots()
 		targetFS = localVss
 	}

doc/040_backup.rst

@@ -56,6 +56,39 @@ snapshot for each volume that contains files to backup. Files are read from the
 VSS snapshot instead of the regular filesystem. This allows to backup files that are
 exclusively locked by another process during the backup.
 
+You can use additional options to change VSS behaviour:
+
+ * ``-o vss.timeout`` specifies timeout for VSS snapshot creation, the default value is 120 seconds
+ * ``-o vss.exclude-all-mount-points`` disable auto snapshotting of all volume mount points
+ * ``-o vss.exclude-volumes`` allows excluding specific volumes or volume mount points from snapshotting
+ * ``-o vss.provider`` specifies VSS provider used for snapshotting
+
+For example a 2.5 minutes timeout with snapshotting of mount points disabled can be specified as
+
+.. code-block:: console
+
+    -o vss.timeout=2m30s -o vss.exclude-all-mount-points=true
+
+and excluding drive ``d:\``, mount point ``c:\mnt`` and volume ``\\?\Volume{04ce0545-3391-11e0-ba2f-806e6f6e6963}\`` as
+
+.. code-block:: console
+
+    -o vss.exclude-volumes="d:;c:\mnt\;\\?\volume{04ce0545-3391-11e0-ba2f-806e6f6e6963}"
+
+VSS provider can be specified by GUID
+
+.. code-block:: console
+
+    -o vss.provider={3f900f90-00e9-440e-873a-96ca5eb079e5}
+
+or by name
+
+.. code-block:: console
+
+    -o vss.provider="Hyper-V IC Software Shadow Copy Provider"
+
+Also ``MS`` can be used as alias for ``Microsoft Software Shadow Copy provider 1.0``.
+
 By default VSS ignores Outlook OST files. This is not a restriction of restic
 but the default Windows VSS configuration. The files not to snapshot are
 configured in the Windows registry under the following key:

internal/fs/fs_local_vss.go

@@ -3,41 +3,108 @@ package fs
 import (
 	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"sync"
+	"time"
 
 	"github.com/restic/restic/internal/errors"
+	"github.com/restic/restic/internal/options"
 )
 
-// ErrorHandler is used to report errors via callback
-type ErrorHandler func(item string, err error) error
+// VSSConfig holds extended options of windows volume shadow copy service.
+type VSSConfig struct {
+	ExcludeAllMountPoints bool          `option:"exclude-all-mount-points" help:"exclude mountpoints from snapshotting on all volumes"`
+	ExcludeVolumes        string        `option:"exclude-volumes" help:"semicolon separated list of volumes to exclude from snapshotting (ex. 'c:\\;e:\\mnt;\\\\?\\Volume{...}')"`
+	Timeout               time.Duration `option:"timeout" help:"time that the VSS can spend creating snapshot before timing out"`
+	Provider              string        `option:"provider" help:"VSS provider identifier which will be used for snapshotting"`
+}
+
+func init() {
+	if runtime.GOOS == "windows" {
+		options.Register("vss", VSSConfig{})
+	}
+}
+
+// NewVSSConfig returns a new VSSConfig with the default values filled in.
+func NewVSSConfig() VSSConfig {
+	return VSSConfig{
+		Timeout: time.Second * 120,
+	}
+}
+
+// ParseVSSConfig parses a VSS extended options to VSSConfig struct.
+func ParseVSSConfig(o options.Options) (VSSConfig, error) {
+	cfg := NewVSSConfig()
+	o = o.Extract("vss")
+	if err := o.Apply("vss", &cfg); err != nil {
+		return VSSConfig{}, err
+	}
+
+	return cfg, nil
+}
+
+// ErrorHandler is used to report errors via callback.
+type ErrorHandler func(item string, err error)
 
 // MessageHandler is used to report errors/messages via callbacks.
 type MessageHandler func(msg string, args ...interface{})
 
+// VolumeFilter is used to filter volumes by it's mount point or GUID path.
+type VolumeFilter func(volume string) bool
+
 // LocalVss is a wrapper around the local file system which uses windows volume
 // shadow copy service (VSS) in a transparent way.
 type LocalVss struct {
 	FS
-	snapshots       map[string]VssSnapshot
-	failedSnapshots map[string]struct{}
-	mutex           sync.RWMutex
-	msgError        ErrorHandler
-	msgMessage      MessageHandler
+	snapshots             map[string]VssSnapshot
+	failedSnapshots       map[string]struct{}
+	mutex                 sync.RWMutex
+	msgError              ErrorHandler
+	msgMessage            MessageHandler
+	excludeAllMountPoints bool
+	excludeVolumes        map[string]struct{}
+	timeout               time.Duration
+	provider              string
 }
 
 // statically ensure that LocalVss implements FS.
 var _ FS = &LocalVss{}
 
+// parseMountPoints try to convert semicolon separated list of mount points
+// to map of lowercased volume GUID pathes. Mountpoints already in volume
+// GUID path format will be validated and normalized.
+func parseMountPoints(list string, msgError ErrorHandler) (volumes map[string]struct{}) {
+	if list == "" {
+		return
+	}
+	for _, s := range strings.Split(list, ";") {
+		if v, err := GetVolumeNameForVolumeMountPoint(s); err != nil {
+			msgError(s, errors.Errorf("failed to parse vss.exclude-volumes [%s]: %s", s, err))
+		} else {
+			if volumes == nil {
+				volumes = make(map[string]struct{})
+			}
+			volumes[strings.ToLower(v)] = struct{}{}
+		}
+	}
+
+	return
+}
+
 // NewLocalVss creates a new wrapper around the windows filesystem using volume
 // shadow copy service to access locked files.
-func NewLocalVss(msgError ErrorHandler, msgMessage MessageHandler) *LocalVss {
+func NewLocalVss(msgError ErrorHandler, msgMessage MessageHandler, cfg VSSConfig) *LocalVss {
 	return &LocalVss{
-		FS:              Local{},
-		snapshots:       make(map[string]VssSnapshot),
-		failedSnapshots: make(map[string]struct{}),
-		msgError:        msgError,
-		msgMessage:      msgMessage,
+		FS:                    Local{},
+		snapshots:             make(map[string]VssSnapshot),
+		failedSnapshots:       make(map[string]struct{}),
+		msgError:              msgError,
+		msgMessage:            msgMessage,
+		excludeAllMountPoints: cfg.ExcludeAllMountPoints,
+		excludeVolumes:        parseMountPoints(cfg.ExcludeVolumes, msgError),
+		timeout:               cfg.Timeout,
+		provider:              cfg.Provider,
 	}
 }
 
@@ -50,7 +117,7 @@ func (fs *LocalVss) DeleteSnapshots() {
 
 	for volumeName, snapshot := range fs.snapshots {
 		if err := snapshot.Delete(); err != nil {
-			_ = fs.msgError(volumeName, errors.Errorf("failed to delete VSS snapshot: %s", err))
+			fs.msgError(volumeName, errors.Errorf("failed to delete VSS snapshot: %s", err))
 			activeSnapshots[volumeName] = snapshot
 		}
 	}
@@ -78,12 +145,27 @@ func (fs *LocalVss) Lstat(name string) (os.FileInfo, error) {
 	return os.Lstat(fs.snapshotPath(name))
 }
 
+// isMountPointIncluded  is true if given mountpoint included by user.
+func (fs *LocalVss) isMountPointIncluded(mountPoint string) bool {
+	if fs.excludeVolumes == nil {
+		return true
+	}
+
+	volume, err := GetVolumeNameForVolumeMountPoint(mountPoint)
+	if err != nil {
+		fs.msgError(mountPoint, errors.Errorf("failed to get volume from mount point [%s]: %s", mountPoint, err))
+		return true
+	}
+
+	_, ok := fs.excludeVolumes[strings.ToLower(volume)]
+	return !ok
+}
+
 // snapshotPath returns the path inside a VSS snapshots if it already exists.
 // If the path is not yet available as a snapshot, a snapshot is created.
 // If creation of a snapshot fails the file's original path is returned as
 // a fallback.
 func (fs *LocalVss) snapshotPath(path string) string {
-
 	fixPath := fixpath(path)
 
 	if strings.HasPrefix(fixPath, `\\?\UNC\`) {
@@ -114,23 +196,36 @@ func (fs *LocalVss) snapshotPath(path string) string {
 
 		if !snapshotExists && !snapshotFailed {
 			vssVolume := volumeNameLower + string(filepath.Separator)
-			fs.msgMessage("creating VSS snapshot for [%s]\n", vssVolume)
 
-			if snapshot, err := NewVssSnapshot(vssVolume, 120, fs.msgError); err != nil {
-				_ = fs.msgError(vssVolume, errors.Errorf("failed to create snapshot for [%s]: %s",
-					vssVolume, err))
+			if !fs.isMountPointIncluded(vssVolume) {
+				fs.msgMessage("snapshots for [%s] excluded by user\n", vssVolume)
 				fs.failedSnapshots[volumeNameLower] = struct{}{}
 			} else {
-				fs.snapshots[volumeNameLower] = snapshot
-				fs.msgMessage("successfully created snapshot for [%s]\n", vssVolume)
-				if len(snapshot.mountPointInfo) > 0 {
-					fs.msgMessage("mountpoints in snapshot volume [%s]:\n", vssVolume)
-					for mp, mpInfo := range snapshot.mountPointInfo {
-						info := ""
-						if !mpInfo.IsSnapshotted() {
-							info = " (not snapshotted)"
+				fs.msgMessage("creating VSS snapshot for [%s]\n", vssVolume)
+
+				var includeVolume VolumeFilter
+				if !fs.excludeAllMountPoints {
+					includeVolume = func(volume string) bool {
+						return fs.isMountPointIncluded(volume)
+					}
+				}
+
+				if snapshot, err := NewVssSnapshot(fs.provider, vssVolume, fs.timeout, includeVolume, fs.msgError); err != nil {
+					fs.msgError(vssVolume, errors.Errorf("failed to create snapshot for [%s]: %s",
+						vssVolume, err))
+					fs.failedSnapshots[volumeNameLower] = struct{}{}
+				} else {
+					fs.snapshots[volumeNameLower] = snapshot
+					fs.msgMessage("successfully created snapshot for [%s]\n", vssVolume)
+					if len(snapshot.mountPointInfo) > 0 {
+						fs.msgMessage("mountpoints in snapshot volume [%s]:\n", vssVolume)
+						for mp, mpInfo := range snapshot.mountPointInfo {
+							info := ""
+							if !mpInfo.IsSnapshotted() {
+								info = " (not snapshotted)"
+							}
+							fs.msgMessage(" - %s%s\n", mp, info)
 						}
-						fs.msgMessage(" - %s%s\n", mp, info)
 					}
 				}
 			}
@@ -173,9 +268,8 @@ func (fs *LocalVss) snapshotPath(path string) string {
 		snapshotPath = fs.Join(snapshot.GetSnapshotDeviceObject(),
 			strings.TrimPrefix(fixPath, volumeName))
 		if snapshotPath == snapshot.GetSnapshotDeviceObject() {
-			snapshotPath = snapshotPath + string(filepath.Separator)
+			snapshotPath += string(filepath.Separator)
 		}
-
 	} else {
 		// no snapshot is available for the requested path:
 		//  -> try to backup without a snapshot