vss

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 13, 2024 License: MIT Imports: 8 Imported by: 0

README

VSS (Volume Shadow Copy Service) API Wrapper

This project provides a Go wrapper for the Windows Volume Shadow Copy Service (VSS) API. It allows you to create, manage, and delete VSS snapshots programmatically.

Features

  • Initialize and manage VSS snapshots.
  • Handle VSS errors with custom error types.
  • Support for various VSS contexts and backup types.
  • Query and manipulate VSS snapshot properties.

Requirements

  • Windows operating system.
  • Go 1.20 or later.

Installation

To use this package, you need to install the required dependencies:

go get github.com/8ugMak1r/go-vss

Usage

Create a VSS Snapshot

To create a VSS snapshot, use the NewVssSnapshot function:

snapshotSet, err := NewVssSnapshot("C:\\", 60, vss.DefaultOption)
if err != nil {
    log.Fatalf("Failed to create VSS snapshot: %v", err)
}

snapshotSet, err := NewVssSnapshots([]string{"C:\\", "D:\\"}, 60, vss.DefaultOption)
if err != nil {
    log.Fatalf("Failed to create VSS snapshot: %v", err)
}
Expose the snapshot to a specified volume
exposeVolume := "Z:"
err = snapshotSet.Snapshots[0].Expose(exposeVolume)
if err != nil {
    log.Fatalf("Failed to expose VSS snapshot: %v", err)
}
log.Printf("Snapshot exposed at: %s", exposedPath)
Delete VSS SnapshotSet

To delete a VSS snapshot, call the Delete method on the VssSnapshot or VssSnapshotSet object:

err := snapshotSet.Delete()
if err != nil {
    log.Fatalf("Failed to delete VSS snapshot: %v", err)
}

Error Handling

The package provides custom error types for handling VSS errors:

  • vssError: Represents an error returned from the VSS API.
  • vssTextError: Represents a textual error message.

Example:

if err != nil {
    if vssErr, ok := err.(*vssError); ok {
        log.Printf("VSS error: %s", vssErr.Error())
    } else {
        log.Printf("Error: %v", err)
    }
}

References

  1. Restic PR #2274 - GitHub
  2. VSS Volume Snapshot Attributes - Microsoft Docs
  3. Volume Shadow Snapshot (VSS) Format - libyal
  4. Volume Shadow Copy BackupComplete and VSS_E_BAD_STATE - Narkive
  5. Difference between VSS Full Backup and VSS Copy - Microsoft Tech Community

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

Documentation

Rendered for windows/amd64

Index

Constants

View Source 
const (
	VSS_S_ASYNC_PENDING   = 0x00042309
	VSS_S_ASYNC_FINISHED  = 0x0004230A
	VSS_S_ASYNC_CANCELLED = 0x0004230B
)

Constants for IVSSAsync api.

Variables

View Source 
var DefaultOption = Option{
	Context:                   VSS_CTX_BACKUP,
	BackupBootableSystemState: false,
	BackupType:                VSS_BT_COPY,
}
View Source 
var UIID_IVSS_ASYNC = ole.NewGUID("{507C37B4-CF5B-4e95-B0AF-14EB9767467E}")

UIID_IVSS_ASYNC defines to GUID of IVSSAsync.

View Source 
var UUID_IVSS = ole.NewGUID("{665c1d5f-c218-414d-a05d-7fef5f9d5c86}")

UUID_IVSS defines the GUID of IVssBackupComponents.665c1d5f-c218-414d-a05d-7fef5f9d5c86

Functions

func HasSufficientPrivilegesForVSS 

func HasSufficientPrivilegesForVSS() error

HasSufficientPrivilegesForVSS returns nil if the user is allowed to use VSS.

Types

type ErrorHandler 

type ErrorHandler func(item string, err error) error

ErrorHandler is used to report errors via callback

type HRESULT 

type HRESULT uint

HRESULT is a custom type for the windows api HRESULT type. 

const (
	S_OK                                            HRESULT = 0x00000000
	E_ACCESSDENIED                                  HRESULT = 0x80070005
	E_OUTOFMEMORY                                   HRESULT = 0x8007000E
	E_INVALIDARG                                    HRESULT = 0x80070057
	VSS_E_BAD_STATE                                 HRESULT = 0x80042301
	VSS_E_UNEXPECTED                                HRESULT = 0x80042302
	VSS_E_PROVIDER_ALREADY_REGISTERED               HRESULT = 0x80042303
	VSS_E_PROVIDER_NOT_REGISTERED                   HRESULT = 0x80042304
	VSS_E_PROVIDER_VETO                             HRESULT = 0x80042306
	VSS_E_PROVIDER_IN_USE                           HRESULT = 0x80042307
	VSS_E_OBJECT_NOT_FOUND                          HRESULT = 0x80042308
	VSS_E_VOLUME_NOT_SUPPORTED                      HRESULT = 0x8004230C
	VSS_E_VOLUME_NOT_SUPPORTED_BY_PROVIDER          HRESULT = 0x8004230E
	VSS_E_OBJECT_ALREADY_EXISTS                     HRESULT = 0x8004230D
	VSS_E_UNEXPECTED_PROVIDER_ERROR                 HRESULT = 0x8004230F
	VSS_E_CORRUPT_XML_DOCUMENT                      HRESULT = 0x80042310
	VSS_E_INVALID_XML_DOCUMENT                      HRESULT = 0x80042311
	VSS_E_MAXIMUM_NUMBER_OF_VOLUMES_REACHED         HRESULT = 0x80042312
	VSS_E_FLUSH_WRITES_TIMEOUT                      HRESULT = 0x80042313
	VSS_E_HOLD_WRITES_TIMEOUT                       HRESULT = 0x80042314
	VSS_E_UNEXPECTED_WRITER_ERROR                   HRESULT = 0x80042315
	VSS_E_SNAPSHOT_SET_IN_PROGRESS                  HRESULT = 0x80042316
	VSS_E_MAXIMUM_NUMBER_OF_SNAPSHOTS_REACHED       HRESULT = 0x80042317
	VSS_E_WRITER_INFRASTRUCTURE                     HRESULT = 0x80042318
	VSS_E_WRITER_NOT_RESPONDING                     HRESULT = 0x80042319
	VSS_E_WRITER_ALREADY_SUBSCRIBED                 HRESULT = 0x8004231A
	VSS_E_UNSUPPORTED_CONTEXT                       HRESULT = 0x8004231B
	VSS_E_VOLUME_IN_USE                             HRESULT = 0x8004231D
	VSS_E_MAXIMUM_DIFFAREA_ASSOCIATIONS_REACHED     HRESULT = 0x8004231E
	VSS_E_INSUFFICIENT_STORAGE                      HRESULT = 0x8004231F
	VSS_E_NO_SNAPSHOTS_IMPORTED                     HRESULT = 0x80042320
	VSS_E_SOME_SNAPSHOTS_NOT_IMPORTED               HRESULT = 0x80042321
	VSS_E_MAXIMUM_NUMBER_OF_REMOTE_MACHINES_REACHED HRESULT = 0x80042322
	VSS_E_REMOTE_SERVER_UNAVAILABLE                 HRESULT = 0x80042323
	VSS_E_REMOTE_SERVER_UNSUPPORTED                 HRESULT = 0x80042324
	VSS_E_REVERT_IN_PROGRESS                        HRESULT = 0x80042325
	VSS_E_REVERT_VOLUME_LOST                        HRESULT = 0x80042326
	VSS_E_REBOOT_REQUIRED                           HRESULT = 0x80042327
	VSS_E_TRANSACTION_FREEZE_TIMEOUT                HRESULT = 0x80042328
	VSS_E_TRANSACTION_THAW_TIMEOUT                  HRESULT = 0x80042329
	VSS_E_VOLUME_NOT_LOCAL                          HRESULT = 0x8004232D
	VSS_E_CLUSTER_TIMEOUT                           HRESULT = 0x8004232E
	VSS_E_WRITERERROR_INCONSISTENTSNAPSHOT          HRESULT = 0x800423F0
	VSS_E_WRITERERROR_OUTOFRESOURCES                HRESULT = 0x800423F1
	VSS_E_WRITERERROR_TIMEOUT                       HRESULT = 0x800423F2
	VSS_E_WRITERERROR_RETRYABLE                     HRESULT = 0x800423F3
	VSS_E_WRITERERROR_NONRETRYABLE                  HRESULT = 0x800423F4
	VSS_E_WRITERERROR_RECOVERY_FAILED               HRESULT = 0x800423F5
	VSS_E_BREAK_REVERT_ID_FAILED                    HRESULT = 0x800423F6
	VSS_E_LEGACY_PROVIDER                           HRESULT = 0x800423F7
	VSS_E_MISSING_DISK                              HRESULT = 0x800423F8
	VSS_E_MISSING_HIDDEN_VOLUME                     HRESULT = 0x800423F9
	VSS_E_MISSING_VOLUME                            HRESULT = 0x800423FA
	VSS_E_AUTORECOVERY_FAILED                       HRESULT = 0x800423FB
	VSS_E_DYNAMIC_DISK_ERROR                        HRESULT = 0x800423FC
	VSS_E_NONTRANSPORTABLE_BCD                      HRESULT = 0x800423FD
	VSS_E_CANNOT_REVERT_DISKID                      HRESULT = 0x800423FE
	VSS_E_RESYNC_IN_PROGRESS                        HRESULT = 0x800423FF
	VSS_E_CLUSTER_ERROR                             HRESULT = 0x80042400
	VSS_E_UNSELECTED_VOLUME                         HRESULT = 0x8004232A
	VSS_E_SNAPSHOT_NOT_IN_SET                       HRESULT = 0x8004232B
	VSS_E_NESTED_VOLUME_LIMIT                       HRESULT = 0x8004232C
	VSS_E_NOT_SUPPORTED                             HRESULT = 0x8004232F
	VSS_E_WRITERERROR_PARTIAL_FAILURE               HRESULT = 0x80042336
	VSS_E_WRITER_STATUS_NOT_AVAILABLE               HRESULT = 0x80042409
)

HRESULT constant values necessary for using VSS api.

func (HRESULT) Str 

func (h HRESULT) Str() string

Str converts a HRESULT to a human readable string.

type IVSSAsync 

type IVSSAsync struct {
	ole.IUnknown
}

IVSSAsync VSS api interface.

func (*IVSSAsync) Cancel 

func (vssAsync *IVSSAsync) Cancel() HRESULT

Cancel calls the equivalent VSS api.

func (*IVSSAsync) QueryStatus 

func (vssAsync *IVSSAsync) QueryStatus() (HRESULT, uint32)

QueryStatus calls the equivalent VSS api.

func (*IVSSAsync) Wait 

func (vssAsync *IVSSAsync) Wait(millis uint32) HRESULT

Wait calls the equivalent VSS api.

func (*IVSSAsync) WaitUntilAsyncFinished 

func (vssAsync *IVSSAsync) WaitUntilAsyncFinished(millis uint32) error

WaitUntilAsyncFinished waits until either the async call is finshed or the given timeout is reached.

type IVSSAsyncVTable 

type IVSSAsyncVTable struct {
	ole.IUnknownVtbl
	// contains filtered or unexported fields
}

IVSSAsyncVTable is the vtable for IVSSAsync.

type IVssBackupComponents 

type IVssBackupComponents struct {
	ole.IUnknown
}

IVssBackupComponents VSS api interface.

func (*IVssBackupComponents) AbortBackup 

func (vss *IVssBackupComponents) AbortBackup() error

AbortBackup calls the equivalent VSS api.

func (*IVssBackupComponents) AddToSnapshotSet 

func (vss *IVssBackupComponents) AddToSnapshotSet(volumeName string, idSnapshot *ole.GUID) (ole.GUID, error)

AddToSnapshotSet calls the equivalent VSS api.

func (*IVssBackupComponents) BackupComplete 

func (vss *IVssBackupComponents) BackupComplete() (*IVSSAsync, error)

BackupComplete calls the equivalent VSS api.

func (*IVssBackupComponents) DeleteSnapshot 

func (vss *IVssBackupComponents) DeleteSnapshot(snapshotID ole.GUID) (int32, ole.GUID, error)

DeleteSnapshots calls the equivalent VSS api.

func (*IVssBackupComponents) DeleteSnapshotSet 

func (vss *IVssBackupComponents) DeleteSnapshotSet(snapshotSetID ole.GUID) (int32, ole.GUID, error)

func (*IVssBackupComponents) DoSnapshotSet 

func (vss *IVssBackupComponents) DoSnapshotSet() (*IVSSAsync, error)

DoSnapshotSet calls the equivalent VSS api.

func (*IVssBackupComponents) ExposeSnapshot 

func (vss *IVssBackupComponents) ExposeSnapshot(snapshotID ole.GUID, destVolume string) error

func (*IVssBackupComponents) GatherWriterMetadata 

func (vss *IVssBackupComponents) GatherWriterMetadata() (*IVSSAsync, error)

GatherWriterMetadata calls the equivalent VSS api.

func (*IVssBackupComponents) GetSnapshotProperties 

func (vss *IVssBackupComponents) GetSnapshotProperties(snapshotID ole.GUID,
	properties *VssSnapshotProperties) error

GetSnapshotProperties calls the equivalent VSS api.

func (*IVssBackupComponents) InitializeForBackup 

func (vss *IVssBackupComponents) InitializeForBackup() error

InitializeForBackup calls the equivalent VSS api.

func (*IVssBackupComponents) IsVolumeSupported 

func (vss *IVssBackupComponents) IsVolumeSupported(volumeName string) (bool, error)

IsVolumeSupported calls the equivalent VSS api.

func (*IVssBackupComponents) PrepareForBackup 

func (vss *IVssBackupComponents) PrepareForBackup() (*IVSSAsync, error)

PrepareForBackup calls the equivalent VSS api.

func (*IVssBackupComponents) SetBackupState 

func (vss *IVssBackupComponents) SetBackupState(selectComponents bool,
	backupBootableSystemState bool, backupType VssBackup, partialFileSupport bool,
) error

SetBackupState calls the equivalent VSS api.

func (*IVssBackupComponents) SetContext 

func (vss *IVssBackupComponents) SetContext(context VssVolumeSnapshotAttribute) error

SetContext calls the equivalent VSS api.

func (*IVssBackupComponents) StartSnapshotSet 

func (vss *IVssBackupComponents) StartSnapshotSet() (ole.GUID, error)

StartSnapshotSet calls the equivalent VSS api.

type IVssBackupComponentsVTable 

type IVssBackupComponentsVTable struct {
	ole.IUnknownVtbl
	// contains filtered or unexported fields
}

IVssBackupComponentsVTable is the vtable for IVssBackupComponents.

type Option 

type Option struct {
	Context                   VssVolumeSnapshotAttribute
	BackupBootableSystemState bool
	BackupType                VssBackup
}

type VssBackup 

type VssBackup uint

VssBackup is a custom type for the windows api VssBackup type. 

const (
	VSS_BT_UNDEFINED VssBackup = iota
	VSS_BT_FULL
	VSS_BT_INCREMENTAL
	VSS_BT_DIFFERENTIAL
	VSS_BT_LOG
	VSS_BT_COPY
	VSS_BT_OTHER
)

VssBackup constant values necessary for using VSS api.

type VssError 

type VssError struct {
	// contains filtered or unexported fields
}

VssError encapsulates errors retruned from calling VSS api.

func (*VssError) Error 

func (e *VssError) Error() string

Error implements the error interface.

type VssObjectType 

type VssObjectType uint

VssObjectType is a custom type for the windows api VssObjectType type. 

const (
	VSS_OBJECT_UNKNOWN VssObjectType = iota
	VSS_OBJECT_NONE
	VSS_OBJECT_SNAPSHOT_SET
	VSS_OBJECT_SNAPSHOT
	VSS_OBJECT_PROVIDER
	VSS_OBJECT_TYPE_COUNT
)

VssObjectType constant values necessary for using VSS api.

type VssSnapshot 

type VssSnapshot struct {
	// contains filtered or unexported fields
}

VssSnapshot wraps windows volume shadow copy api (vss) via a simple interface to create and delete a vss snapshot.

func (*VssSnapshot) Delete 

func (p *VssSnapshot) Delete() error

Delete deletes the created snapshot.

func (*VssSnapshot) Expose 

func (p *VssSnapshot) Expose(volume string) error

func (*VssSnapshot) GetSnapshotDeviceObject 

func (p *VssSnapshot) GetSnapshotDeviceObject() string

GetSnapshotDeviceObject returns root path to access the snapshot files and folders.

func (*VssSnapshot) GetSnapshotID 

func (p *VssSnapshot) GetSnapshotID() string

func (*VssSnapshot) GetVolumeName 

func (p *VssSnapshot) GetVolumeName() string

type VssSnapshotProperties 

type VssSnapshotProperties struct {
	// contains filtered or unexported fields
}

VssSnapshotProperties defines the properties of a VSS snapshot as part of the VSS api.

func (*VssSnapshotProperties) GetSnapshotDeviceObject 

func (p *VssSnapshotProperties) GetSnapshotDeviceObject() string

GetSnapshotDeviceObject returns root path to access the snapshot files and folders.

type VssSnapshotSet 

type VssSnapshotSet struct {
	SnapshotSetID ole.GUID
	Snapshots     []VssSnapshot
	// contains filtered or unexported fields
}

func NewVssSnapshot 

func NewVssSnapshot(volume string, timeoutInSeconds uint, option Option) (VssSnapshotSet, error)

NewVssSnapshot creates a new vss snapshot. If creating the snapshots doesn't finish within the timeout an error is returned.

func NewVssSnapshots 

func NewVssSnapshots(volumes []string, timeoutInSeconds uint, option Option) (VssSnapshotSet, error)

NewVssSnapshots creates a new vss snapshot. If creating the snapshots doesn't finish within the timeout an error is returned.

func (*VssSnapshotSet) Delete 

func (p *VssSnapshotSet) Delete() error

type VssTextError 

type VssTextError struct {
	// contains filtered or unexported fields
}

VssError encapsulates errors retruned from calling VSS api.

func (*VssTextError) Error 

func (e *VssTextError) Error() string

Error implements the error interface.

type VssVolumeSnapshotAttribute 

type VssVolumeSnapshotAttribute uint

VssVolumeSnapshotAttribute is a custom type for the windows api _VSS_VOLUME_SNAPSHOT_ATTRIBUTES type. https://docs.microsoft.com/en-us/windows/win32/api/vss/ne-vss-vss_volume_snapshot_attributes https://github.com/libyal/libvshadow/blob/main/documentation/Volume%20Shadow%20Snapshot%20(VSS)%20format.asciidoc#422-store-attribute-flags 

const (
	VSS_VOLSNAP_ATTR_PERSISTENT           VssVolumeSnapshotAttribute = 0x00000001
	VSS_VOLSNAP_ATTR_NO_AUTORECOVERY      VssVolumeSnapshotAttribute = 0x00000002
	VSS_VOLSNAP_ATTR_CLIENT_ACCESSIBLE    VssVolumeSnapshotAttribute = 0x00000004
	VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE      VssVolumeSnapshotAttribute = 0x00000008
	VSS_VOLSNAP_ATTR_NO_WRITERS           VssVolumeSnapshotAttribute = 0x00000010
	VSS_VOLSNAP_ATTR_TRANSPORTABLE        VssVolumeSnapshotAttribute = 0x00000020
	VSS_VOLSNAP_ATTR_NOT_SURFACED         VssVolumeSnapshotAttribute = 0x00000040
	VSS_VOLSNAP_ATTR_NOT_TRANSACTED       VssVolumeSnapshotAttribute = 0x00000080
	VSS_VOLSNAP_ATTR_HARDWARE_ASSISTED    VssVolumeSnapshotAttribute = 0x00010000
	VSS_VOLSNAP_ATTR_DIFFERENTIAL         VssVolumeSnapshotAttribute = 0x00020000
	VSS_VOLSNAP_ATTR_PLEX                 VssVolumeSnapshotAttribute = 0x00040000
	VSS_VOLSNAP_ATTR_IMPORTED             VssVolumeSnapshotAttribute = 0x00080000
	VSS_VOLSNAP_ATTR_EXPOSED_LOCALLY      VssVolumeSnapshotAttribute = 0x00100000
	VSS_VOLSNAP_ATTR_EXPOSED_REMOTELY     VssVolumeSnapshotAttribute = 0x00200000
	VSS_VOLSNAP_ATTR_AUTORECOVER          VssVolumeSnapshotAttribute = 0x00400000
	VSS_VOLSNAP_ATTR_ROLLBACK_RECOVERY    VssVolumeSnapshotAttribute = 0x00800000
	VSS_VOLSNAP_ATTR_DELAYED_POSTSNAPSHOT VssVolumeSnapshotAttribute = 0x01000000
	VSS_VOLSNAP_ATTR_TXF_RECOVERY         VssVolumeSnapshotAttribute = 0x02000000
	VSS_VOLSNAP_ATTR_FILE_SHARE           VssVolumeSnapshotAttribute = 0x4000000
)
const (
	VSS_CTX_BACKUP                    VssVolumeSnapshotAttribute = 0x00000000 // default
	VSS_CTX_APP_ROLLBACK              VssVolumeSnapshotAttribute = 0x00000009 // VSS_VOLSNAP_ATTR_PERSISTENT | VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE
	VSS_CTX_CLIENT_ACCESSIBLE_WRITERS VssVolumeSnapshotAttribute = 0x0000000d // VSS_VOLSNAP_ATTR_PERSISTENT | VSS_VOLSNAP_ATTR_CLIENT_ACCESSIBLE | VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE
	VSS_CTX_FILE_SHARE_BACKUP         VssVolumeSnapshotAttribute = 0x00000010 // VSS_VOLSNAP_ATTR_NO_WRITERS
	VSS_CTX_NAS_ROLLBACK              VssVolumeSnapshotAttribute = 0x00000019 // VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE | VSS_VOLSNAP_ATTR_NO_WRITERS | VSS_VOLSNAP_ATTR_NO_AUTORECOVERY
	VSS_CTX_CLIENT_ACCESSIBLE         VssVolumeSnapshotAttribute = 0x0000001d //  VSS_VOLSNAP_ATTR_PERSISTENT | VSS_VOLSNAP_ATTR_CLIENT_ACCESSIBLE | VSS_VOLSNAP_ATTR_NO_AUTO_RELEASE | VSS_VOLSNAP_ATTR_NO_WRITERS
	VSS_CTX_ALL                       VssVolumeSnapshotAttribute = 0xffffffff //
)

VssContext constant values necessary for using VSS api. https://github.com/libyal/libvshadow/blob/main/documentation/Volume%20Shadow%20Snapshot%20(VSS)%20format.asciidoc#421-store-snapshot-context

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.