Backup Restore & VM Cloning

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
   • Servy-Dump.ps1
   • Servy-Restore.ps1
2. Security Warnings & Credential Handling
3. Virtual Machine Cloning & Migration (VMware / Hyper-V)
   • 1. Will cloning VMs or deploying from templates break entropy and encryption?
   • 2. Will changing Virtual CPU or RAM configurations break encryption?
   • 3. Will changing Virtual NIC MAC addresses break encryption?
   • 4. Key Storage vs. Dynamic Entropy Clarification
4. Recommended VMware / Golden Image Deployment Workflow

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:

• Servy-Dump.ps1
• 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. All XML definitions are then compressed into a single consolidated .zip archive.

Script Features

• Native Interop: Queries Servy.db using Windows native %SystemRoot%\System32\winsqlite3.dll without requiring external DLL installations.
• Sanitized Filenames: Automatically sanitizes service names containing illegal filesystem characters.
• 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

Parameters

Parameter	Type	Required	Description
-DestinationArchivePath	String	Yes	Path specifying the target zip archive file (e.g., C:\Backups\Servy_Dump.zip).
-Overwrite	Switch	No	Forces the script to replace the destination archive if it already exists.

Exit Codes

Code	Meaning
0	Success. Note this is 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 imported.
3	The destination archive already exists and -Overwrite was not specified.
6	Complete Export Failure. No service configurations could be exported; no output archive was generated.
7	Partial Export Warning. The dump archive was successfully created, but one or more services failed to export.

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, 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

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).

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 imported.
3	The specified dump archive does not exist.

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. While master passwords are excluded, sensitive data such as execution parameters, API keys, command-line arguments, environment variables, and pre/post hooks are written in plaintext.

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 LOCALSYSYEM 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 PowerShell, and re-run executable hardening via Set-ServyExePermissions.ps1.

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?

YES (for the cloned instances).

When a virtual machine is cloned or deployed from a template, Windows generates a new system MachineGuid (or Sysprep resets the system SID and GUID).

Because Servy binds its master AES encryption key (aes_key.dat) to a combination of Windows DPAPI and host registry entropy (HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\MachineGuid):

• The source machine / template master remains unaffected.
• The cloned instances will fail to decrypt pre-existing encrypted fields (Password, Parameters, EnvironmentVariables, etc.) stored inside %ProgramData%\Servy\db\Servy.db.

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. Ensure %ProgramData%\Servy is empty/uninitialized (Purge stale db/security folders)
         ├── 5. Run Servy-Restore.ps1 -DumpArchivePath "C:\Staging\Servy_Dump.zip" -Install
         ├── 6. Re-enter Service Account Passwords (servy-cli / Servy Manager)
         └── 7. Run Set-ServyExePermissions.ps1 -TargetAccount "<RunnerAccount>"

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. 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.
5. Re-apply Logon Credentials & Binary Hardening: Re-assign custom service runner credentials and enforce mandatory binary permissions:

   .\Set-ServyExePermissions.ps1 -TargetAccount "DOMAIN\svc-runner"