Skip to content

Backup Restore & VM Cloning

Jump to bottom
aelassas edited this page Aug 29, 2026 · 33 revisions

This document covers backup and recovery procedures for Servy service configurations using the official PowerShell utility scripts (Servy-Dump.ps1 and Servy-Restore.ps1), along with architectural guidelines for virtual machine cloning, imaging, and template migrations (VMware, Hyper-V, Azure, AWS).

Table of Contents

  1. Backup & Restore Utility Scripts
  2. Security Warnings & Credential Handling
  3. Virtual Machine Cloning & Migration (VMware / Hyper-V)
  4. Recommended VMware / Golden Image Deployment Workflow
  5. See Also

Backup & Restore Utility Scripts

Starting from v10.0, Servy includes two administrative PowerShell scripts located directly in %ProgramFiles%\Servy\ (or the root of portable distributions) to streamline environment migrations, backup routines, and template-based provisioning. For versions prior to v10.0, the scripts can be downloaded directly from the official repository:

For the .NET Framework 4.8 build, the scripts can be downloaded directly from the net48 branch:

Important

SYSTEM REQUIREMENTS & OS FLOORS

Both scripts require Administrator privileges (exit code 1).

  • main Branch (.NET 10.0+ / Modern Builds):

    • Servy-Dump.ps1: Requires Windows 10 / Windows Server 2016 or later and PowerShell 5.1+. It queries Servy.db using the OS-native %SystemRoot%\System32\winsqlite3.dll with native UTF-16 marshaling.
    • Servy-Restore.ps1: Requires Windows 10 / Windows Server 2016 or later and PowerShell 5.1+.

  • net48 Branch (.NET Framework 4.8 / Legacy Builds):

    • Servy-Dump.ps1: Supports Windows 7 SP1 / Windows Server 2008 R2 or later and PowerShell 2.0+. Uses a multi-tier database inspection layer (prefers System.Data.SQLite.dll or e_sqlite3.dll in the Servy installation directory, with dynamic fallback to winsqlite3.dll / sqlite3.dll).
    • Servy-Restore.ps1: Supports Windows 7 SP1 / Windows Server 2008 R2 or later and PowerShell 2.0+. Uses native COM Shell.Application extraction as a fallback when Expand-Archive or .NET ZipFile is unavailable.

  • Cross-Version Restore Compatibility:

    Servy-Restore.ps1 has no direct SQLite interop dependency - it operates via Import-ServyServiceConfig. Dump archives generated on modern machines can be restored directly onto legacy Windows 7 / Server 2008 R2 targets using the net48 branch version of Servy-Restore.ps1.

Servy-Dump.ps1

Servy-Dump.ps1 inspects the local Servy SQLite database (%ProgramData%\Servy\db\Servy.db), enumerates all registered service definitions, and exports each service's configuration into an individual XML file using Export-ServyServiceConfig. See Export & Import Services for the configuration file format and the complete field reference. All XML definitions are then compressed into a single consolidated .zip archive along with a .sha256 sidecar file for integrity verification.

Script Features

  • Native & Multi-Tier Interop: On main branch, queries Servy.db using Windows native %SystemRoot%\System32\winsqlite3.dll without requiring external DLL installations. On net48 branch, uses managed System.Data.SQLite.dll / e_sqlite3.dll with dynamic kernel32 fallback.
  • Per-Service Error Isolation: Individual export failures do not delete successfully exported files or abort the entire process. If at least one service exports, the zip archive is produced and exit code 7 is returned.
  • Sanitized Filenames & Encoding Safety: Automatically sanitizes service names containing illegal filesystem characters and uses native UTF-16 marshaling to safely handle Unicode service names (e.g., Café-Svc or 服务).
  • Safety Checks: Requires elevated Administrator privileges and blocks accidental overwrites unless explicit permission is granted.

Syntax & Usage

# Basic usage (fails with exit code 3 if destination archive already exists)
.\Servy-Dump.ps1 -DestinationArchivePath "C:\Backups\Servy_Dump.zip"

# Force overwrite of existing backup archive
.\Servy-Dump.ps1 -DestinationArchivePath "C:\Backups\Servy_Dump.zip" -Overwrite

# Force overwrite of existing backup archive and uninstalls each successfully exported service from the Windows SCM and removes it from the Servy database
.\Servy-Dump.ps1 -DestinationArchivePath "C:\Backups\Servy_Dump.zip" -Overwrite -Uninstall

Parameters

Parameter Type Required Description
-DestinationArchivePath String Yes Target zip archive destination file (e.g., C:\Backups\Servy_Dump.zip). If a directory path or trailing separator is provided, it writes to $DestinationArchivePath\Servy_Dump.zip; if no file extension is specified, .zip is appended. Use -Overwrite to replace an existing archive.
-Overwrite Switch No Overwrite the destination dump archive if it already exists.
-Uninstall Switch No When present, uninstalls each successfully exported service from the Windows SCM and removes it from the Servy database.

Exit Codes

Code Meaning
0 Success. All registered service configurations were successfully exported and archived. (Note: Also returned when no database exists or no services are registered, in which case no archive is written).
1 Not running with Administrator privileges.
2 The Servy PowerShell module (Servy.psm1) could not be located or imported.
3 The destination archive already exists and -Overwrite was not specified.
4 The database could not be read, the target destination path/directory is unwritable, or ACL hardening failed.
5 Setup Compilation Failure. Failed to compile native SQLite dynamic P/Invoke assembly bindings.
6 Complete Export Failure. No service configurations could be exported; no output archive was generated.
7 The dump archive was successfully created, but one or more services failed to export or uninstall.
8 Archive Staging Mismatch. Staged configuration count does not match exported count; dump aborted.

Note

In an automated backup job, check that the archive file exists and is non-empty in addition to checking the exit code. Exit code 0 alone does not guarantee an archive was produced.

Servy-Restore.ps1

Servy-Restore.ps1 ingests a consolidated .zip backup archive generated by Servy-Dump.ps1, verifies its integrity against the accompanying .sha256 sidecar file (which must be located in the same directory as the dump file), extracts the individual service XML files into a secure staging location, and imports each configuration into the local Servy instance via Import-ServyServiceConfig.

Syntax & Usage

# Restore service configurations (imports definitions into Servy database)
.\Servy-Restore.ps1 -DumpArchivePath "C:\Backups\Servy_Dump.zip"

# Restore service configurations AND install them into Windows SCM
.\Servy-Restore.ps1 -DumpArchivePath "C:\Backups\Servy_Dump.zip" -Install

# Restore service configurations AND install them into Windows SCM without SHA-256 sidecar integrity verification
.\Servy-Restore.ps1 -DumpArchivePath "C:\Backups\Servy_Dump.zip" -Install -SkipIntegrityCheck

Warning

RESTORING OVERWRITES EXISTING SERVICES

Servy-Restore.ps1 imports every configuration in the archive unconditionally. If a service of the same name already exists on the target machine, its stored configuration is replaced, and with -Install its Windows SCM registration is rewritten as well. There is no prompt and no undo: any change made on the target since the dump was taken is lost.

This is harmless in the cloning workflow below, where the vault is purged first, but be deliberate when restoring onto a machine that is already in service. Take a fresh dump of the target before restoring an older archive over it:

.\Servy-Dump.ps1 -DestinationArchivePath "C:\Backups\Servy_PreRestore.zip" -Overwrite

Parameters

Parameter Type Required Description
-DumpArchivePath String Yes Path specifying the target .zip backup archive to restore.
-Install Switch No Automatically registers each imported service with the Windows Service Control Manager (SCM).
-SkipIntegrityCheck Switch No Skips SHA-256 sidecar verification entirely: the archive is restored without an integrity check, whether the .sha256 sidecar is absent, stale, or mismatching.
-MaxAllowedEntries Int32 No Maximum number of entries permitted in the archive to prevent zip bomb attacks during extraction (defaults to 1000, range: 1-100,000).
-MaxUncompressedBytes Int64 No Maximum total uncompressed size in bytes permitted during extraction (defaults to 104857600 bytes / 100 MB, range: 1-10737418240 bytes / 10 GB).

Exit Codes

Code Meaning
0 Success. Also returned when the archive contains no XML configuration files, in which case nothing is imported.
1 Not running with Administrator privileges.
2 The Servy PowerShell module (Servy.psm1) could not be located or imported.
3 The specified dump archive does not exist.
4 I/O & Extraction Failure. The archive could not be extracted, ACL hardening failed, or malformed entries were detected.
5 Checksum Verification Failure. The .sha256 sidecar is missing (without -SkipIntegrityCheck) or a hash mismatch was detected.
6 Complete Import Failure. No service configurations could be imported from the archive.
7 Partial Import Warning. The restore completed, but one or more services failed to import.

Security Warnings & Credential Handling

Caution

CRITICAL SECURITY WARNING: UNENCRYPTED CONFIGURATION

The backup .zip archive generated by Servy-Dump.ps1 contains unencrypted plain-text XML files. No credentials of any kind are exported - UserAccount, Password and RunAsLocalSystem are omitted from every export - but sensitive data such as execution parameters, API keys, command-line arguments, environment variables, and pre/post hooks are written in plaintext. Restrict access to generated dump archives to authorized administrative personnel only. See Export & Import Services for the full field reference.

The archive also contains every executable path the service configuration references: the wrapped program and its startup directory, the failure program, and the pre-launch, post-launch, pre-stop and post-stop hook executables with their arguments and environment.

Because restored services default to LocalSystem (see the callout below), anyone able to modify a dump archive controls what runs as LocalSystem on every machine restored from it. Restrict write access as strictly as read access, and store dump archives in a directory whose ACL grants only Administrators and SYSTEM - the same protection the installer applies to %ProgramData%\Servy:

icacls "C:\Staging" /inheritance:r /grant:r "*S-1-5-32-544:(OI)(CI)F" "*S-1-5-18:(OI)(CI)F"

Important

CREDENTIAL RESET TO LOCALSYSTEM ON RESTORE

For security reasons, Windows Service Account logon credentials (Usernames and Passwords) are never exported into XML dumps. Restoring configurations via Servy-Restore.ps1, servy-cli, or Servy Manager will automatically reset all service logon identities to LocalSystem. Post-Restore Action Required: If any restored service runs under a custom account (.\test_svc, DOMAIN\svc_account, or gMSA), you must manually re-enter the Logon Username and Password via Servy Manager, servy-cli or the PowerShell module, and re-run executable hardening via Set-ServyExePermissions.ps1 (see Security).

What Does Not Survive a Dump/Restore Cycle

Not every field in a service definition is carried through an export. Plan for these before relying on a restored clone being identical to its template:

Field Behaviour on import Why it matters after a clone
UserAccount Not exported; reset to LocalSystem Re-enter for every service using a custom identity
Password Not exported; reset to empty Re-enter alongside UserAccount
RunAsLocalSystem Not exported; forced to the LocalSystem baseline This is the field that causes the reset above
Pid Silently ignored Runtime state; expected
PreviousStopTimeout Silently ignored Recovery tuning is not carried over
ActiveStdoutPath Silently ignored The resolved log destination is re-derived on the clone
ActiveStderrPath Silently ignored As above

A warning is written to the log when a custom identity is discarded on import. The four silently-ignored fields produce no warning at all, so check them explicitly if your template depends on them.

See Export & Import Services for the complete field reference.

Virtual Machine Cloning & Migration (VMware / Hyper-V)

When managing virtualized infrastructure (VMware vSphere, Hyper-V, Azure VMs, AWS EC2), understanding how Servy handles cryptographic machine identity is essential for template-based provisioning and image cloning.

1. Will cloning VMs or deploying from templates break entropy and encryption?

It depends on whether the clone is generalized.

Servy binds its master AES key to two machine-specific inputs: the Windows DPAPI LocalMachine master key, and registry entropy read from HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\MachineGuid.

  • Sysprep / guest customization (sysprep /generalize, VMware Guest OS Customization, Azure and AWS image deployment): YES, decryption breaks. Generalization regenerates both the machine SID and MachineGuid, and resets the DPAPI machine keys. The cloned instance cannot decrypt Password, Parameters, EnvironmentVariables or any other protected field in %ProgramData%\Servy\db\Servy.db. Follow the workflow below.

  • A raw clone with no generalization (VMware "Clone" without customization, a Hyper-V export/import, a restored disk image): NO, decryption continues to work. Both the registry hive and the DPAPI machine keys are files on the copied disk, so they are identical to the source and the existing vault stays readable. No purge or re-import is required.

  • The source machine / template master is unaffected in either case.

Warning

A raw clone keeps the source machine's keys, which means every clone shares them. If that is not acceptable in your environment, generalize the image and follow the workflow below so each instance derives its own key.

2. Will changing Virtual CPU or RAM configurations break encryption?

NO.

Servy does not bind its keying material to hardware metrics such as CPU ID, RAM capacity, BIOS UUIDs, or motherboard serial numbers. It binds strictly to the Windows DPAPI master key and the OS registry value (MachineGuid). Modifying vCPU or RAM allocations in VMware has zero impact on cryptographic decryption.

3. Will changing Virtual NIC MAC addresses break encryption?

NO.

Servy does not inspect or bind keying material to network adapters, IP addresses, or MAC addresses. Swapping virtual NICs, reconfiguring networks, or upgrading VMware Tools will not invalidate existing decryption keys.

4. Key Storage vs. Dynamic Entropy Clarification

  • Key Storage: Encrypted key material (aes_key.dat) is stored on disk in %ProgramData%\Servy\security\.
  • Dynamic Entropy: Additional runtime entropy is derived directly from the operating system registry (MachineGuid).

Warning

If HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\MachineGuid is missing or unreadable, Servy falls back to the machine's hostname as its entropy source and logs CRITICAL SECURITY DEGRADATION to the event log and the file log. A hostname is predictable and is not unique per OS installation, so two clones that share a name would derive the same entropy. If you see that message on a provisioned VM, confirm the registry value was created by the guest customization step before putting the machine into service.

Note

Key material written by Servy 7.8 or earlier carries no entropy. Servy reads it through a compatibility path, logs a SECURITY DEGRADATION WARNING, and transparently re-saves it in the entropy-protected format on first successful read. Seeing that warning once per file during an upgrade is expected.

When a virtual machine is cloned:

  1. Windows DPAPI host keys change.
  2. Registry MachineGuid changes.

Both alterations invalidate the decryption capability of any .dat security files copied over from the original VM.

Recommended VMware / Golden Image Deployment Workflow

To avoid DPAPI decryption failures across cloned virtual machines, do not attempt to copy %ProgramData%\Servy\security\aes_key.dat between OS instances. Instead, leverage Servy-Dump.ps1 and Servy-Restore.ps1 within your automated post-clone customization pipeline:

[ Golden Image / Template ]
         │
         ├── 1. Install Servy (%ProgramFiles%\Servy)
         ├── 2. Run Servy-Dump.ps1 (if pre-configured services exist)
         │      └─> .\Servy-Dump.ps1 -DestinationArchivePath "C:\Sysprep\Servy_Base_Dump.zip" -Overwrite
         │
         ▼ (VMware Clone / Sysprep Deployment)
[ New Cloned VM Instance ]
         │
         ├── 3. Execute Sysprep / Guest Customization (New IP, Hostname, MachineGuid)
         ├── 4. Purge the stale vault: delete %ProgramData%\Servy\db and %ProgramData%\Servy\security
         ├── 5. Run Servy-Restore.ps1 -DumpArchivePath "C:\Sysprep\Servy_Base_Dump.zip" -Install
         ├── 6. Re-enter Service Account Passwords & Run Set-ServyExePermissions.ps1
         └── 7. Remove Staged Dump Archive (C:\Sysprep\Servy_Base_Dump.zip)

Automation Steps

  1. Prepare Golden Template: Install Servy on the master image.
  2. Export Base Configurations (Optional): If your template includes standard base service definitions, run: 
    .\Servy-Dump.ps1 -DestinationArchivePath "C:\Sysprep\Servy_Base_Dump.zip" -Overwrite
  3. Deploy Clone: Clone the VM in VMware and execute standard Guest OS Customization / Sysprep.
  4. Purge the Stale Vault: On the cloned VM, delete the database and key material inherited from the template. Servy recreates both folders, with their hardened ACLs, on the next CLI operation. 
    Remove-Item -LiteralPath "$env:ProgramData\Servy\db" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath "$env:ProgramData\Servy\security" -Recurse -Force -ErrorAction SilentlyContinue
  5. Restore Configurations: On first boot of the newly cloned VM, run: 
    .\Servy-Restore.ps1 -DumpArchivePath "C:\Sysprep\Servy_Base_Dump.zip" -Install
    Servy will automatically initialize a brand-new aes_key.dat tied to the new VM's unique MachineGuid and DPAPI scope.
  6. Re-apply Logon Credentials & Binary Hardening: Re-assign custom service runner credentials and enforce mandatory binary permissions: 
    .\Set-ServyExePermissions.ps1 -TargetAccount "DOMAIN\svc-runner"
  7. Remove the staged dump archive. The archive is plaintext (see the security warning above) and, staged inside the golden image, it is replicated to every VM deployed from that template. Delete it as the last step of guest customization: 
    Remove-Item -LiteralPath "C:\Sysprep\Servy_Base_Dump.zip" -Force -ErrorAction SilentlyContinue

Important

Deleting the staged dump archive on the template is not enough - the clone gets its own copy from the image, so the removal has to run on each deployed VM after the restore.

Note

Only db and security folders need to be removed from the vault %ProgramData%\Servy. Deleting all of %ProgramData%\Servy also discards logs\ and recovery\, which is unnecessary and costs you the service history from the template.

See Also

Copyright © Akram El Assas. All rights reserved.

  1. Home
  2. Overview
  3. Installation Guide
  4. Advanced Configuration
  5. Usage
  6. Servy Desktop App
  7. Servy Manager
  8. Servy CLI
  9. PowerShell Module
  10. Examples & Recipes
  11. Logging & Log Rotation
  12. Health Monitoring & Recovery
  13. Environment Variables
  14. Service Dependencies
  15. Pre-Launch & Post-Launch Actions
  16. Pre-Stop & Post-Stop Actions
  17. Shutdown & Teardown
  18. Export/Import Services
  19. Automation & CI/CD
  20. Integration with Monitoring Tools
  21. Service Event Notifications
  22. Comparison with Alternatives
  23. Security
  24. Backup/Restore & VM Cloning
  25. Architecture
  26. Building from Source
  27. Troubleshooting
  28. FAQ

Clone this wiki locally