User Guide for VM Backup and Snapshot Retention Script

This script automates the process of backing up virtual machines (VMs) and managing snapshot retention. It reads configurations from an external INI file, allowing for customizable settings without modifying the script directly. The script uses PowerShell cmdlets and RoboCopy for backup operations and manages snapshots for virtual machines.

• Automated VM snapshot creation.
• Retention management for old snapshots.
• Configurable backup paths and options.
• Dynamic inclusion of VMs via the INI file.
• Detailed logging of operations.
• Fully customizable through an easy-to-use configuration file.

1. System Requirements:
   • Windows Server or Windows 10/11 with Hyper-V installed.
   • PowerShell 5.0 or later.

1. Required Permissions:
   • Administrative privileges to manage VMs and access file paths.

1. Dependencies:
   • RoboCopy (built into Windows).

1. Configuration File:
   • A properly formatted INI file must be created and configured.

All configurations are stored in the options.ini file.

[Settings]
RetentionDays = 7
LocalPath = C:\VMBackups
RemotePath = \\BackupServer\VMs
LogPath = C:\VMLogs
RoboOpts = /MIR /e /FFT /Z /XA:H /W:5 /compress
 
[VMs]
VM1 = MyVirtualMachine1
VM2 = MyVirtualMachine2
VM3 = MyVirtualMachine3

1. [Settings]
   1. RetentionDays: Number of days to retain snapshots before deletion. Older snapshots will be automatically removed.
      1. Default: 7
      2. Example: RetentionDays = 14

1. LocalPath: Local directory where the VM files are stored.
   1. Example: LocalPath = C:\VMBackups

1. RemotePath: Remote destination directory for backups. Use UNC paths for network locations.
   1. Example: RemotePath = \\BackupServer\VMs

1. LogPath: Directory where log files will be saved.
   1. Example: LogPath = C:\VMLogs

1. RoboOpts: Customizable options for RoboCopy. These should be formatted as a single string of space-separated options.
   1. Default: /MIR /e /FFT /Z /XA:H /W:5 /compress
   2. Example: RoboOpts = /S /ZB /R:3

1. [VMs]
   1. List of VMs to be backed up. Each entry should be in the format VMx = VMName, where x is a unique identifier and VMName is the name of the virtual machine.
      1. Example:

[VMs]
VM1 = MyVirtualMachine1
VM2 = MyVirtualMachine2
VM3 = MyVirtualMachine3

1. Snapshot Management
   1. The script creates a snapshot for each VM listed in the INI file.
   2. Old snapshots are removed based on the retention period defined in the RetentionDays parameter.

1. Backup Process
   1. The script uses RoboCopy to transfer VM files from the LocalPath to the RemotePath.
   2. Configurable options for RoboCopy allow fine-tuning of backup behavior.

1. Logging
   1. All operations are logged in a file created in the directory specified by LogPath.
   2. Log entries include timestamps and descriptions of actions performed.

1. Open the ''options.ini'' file in a text editor.
2. Modify the parameters in the ''[Settings]'' and ''[VMs]'' sections as needed.
3. Save the file.

1. Open a PowerShell window with administrative privileges.
2. Navigate to the directory containing the script.
3. Execute the script:

.\BackupScript.ps1

4. The script will automatically read the ''options.ini'' file, process VMs, and log the operations.

• Check the log files in the directory specified by LogPath for details of the backup process.

1. Error: "Invalid Parameter #3"
   1. Cause: RoboCopy options are not split correctly.
   2. Solution: Ensure RoboOpts in the INI file is a valid string of space-separated options.

1. Error: "Access Denied"
   1. Cause: Insufficient permissions to access VM files or remote path.
   2. Solution: Run PowerShell as an administrator and verify permissions for the specified directories.

1. Error: "VM not found"
   1. Cause: VM name in the INI file does not match an existing VM.
   2. Solution: Verify the VM names in the [VMs] section of the INI file.

1. The RoboOpts parameter allows you to customize the behavior of RoboCopy.
2. Example Options:
   1. /MIR: Mirrors the directory structure.
   2. /Z: Enables restartable mode for interrupted transfers.
   3. /XA:H: Excludes hidden files.
   4. /R:N: Specifies the number of retry attempts.

1. To add a VM:

1. Add a new entry in the [VMs] section of the INI file.

1. Example: VM4 = MyVirtualMachine4

2. Save the INI file.

1. To remove a VM:

1. Delete the corresponding entry in the [VMs] section.

  2. Save the INI file.

1. Log Management: Periodically clean up old logs in the LogPath directory to save space.
2. INI File Updates: Review and update the INI file as necessary to reflect changes in the VM environment.
3. Script Updates: Check for script updates to ensure compatibility with the latest systems and features.

For questions or issues, please contact the script author or system administrator.