=== Purpose ===
This PowerShell script automates the process of:
* Backing up Hyper-V virtual machines (VMs).
* Retaining snapshots for a configurable period.
* Logging the entire process for audit and troubleshooting purposes.
* Sending email notifications upon success or failure.
* Providing a Windows-like progress box for user feedback.

=== Features ===
* INI-Based Configuration: All settings, including email and paths, are configured via an easy-to-edit `.ini` file.
* Snapshot Retention: Removes old snapshots based on the retention period defined in the `.ini` file.
* Automated Backup: Uses `RoboCopy` to back up VM files to a remote or local destination.
* Email Notifications: Notifies the user of the script's success or failure.
* Progress Box: Displays a Windows-like GUI progress bar during the backup process.

=== Prerequisites ===
- PowerShell Version: Ensure PowerShell 5.1 or later is installed.
- Hyper-V Module: The script uses `Checkpoint-VM`, `Get-VMSnapshot`, and `Remove-VMSnapshot`. The Hyper-V PowerShell module must be installed.
- INI File Configuration: The script relies on an `.ini` file for settings.
- Windows Forms Assembly: The script uses `System.Windows.Forms` for the progress box. This is included by default on Windows.

== INI File ==
The script uses an `.ini` file located at:
* `C:\Program Files\SyncVM\options.ini`

Below is an example `.ini` file with all available settings:

```ini
[Settings]
RetentionDays = 7 ; Number of days to retain snapshots
LocalPath = C:\HyperV\VMs ; Local directory where VM files are stored
RemotePath = \\BackupServer\Backups ; Remote directory for storing backups
LogPath = C:\HyperV\Logs ; Path to save log files
RoboOpts = /MIR /E /FFT /Z /XA:H /W:5 /compress ; Options for RoboCopy

[VMs]
VM1 = TestVM1
VM2 = TestVM2
VM3 = TestVM3

[Email]
To = admin@example.com ; Email address to send notifications to
From = backup@example.com ; Email address to send notifications from
SMTPServer = smtp.example.com ; SMTP server for sending email
SMTPPort = 587 ; SMTP port (e.g., 587 for TLS, 25 for standard)
SMTPUsername = username@example.com ; Username for SMTP authentication
SMTPPassword = yourpassword ; Password for SMTP authentication
SubjectPrefix = [VM Backup] ; Prefix for email subject lines

[Settings]:

RetentionDays: How long (in days) to retain VM snapshots.
LocalPath: Directory containing VM files.
RemotePath: Destination for VM backups.
LogPath: Location of the log files.
RoboOpts: Options for RoboCopy. Adjust according to your needs.
[VMs]:

List of VM names to back up.
[Email]:

SMTP settings for sending email notifications.
Authentication is optional; if omitted, the script attempts to send emails without it.

Download and Save the Script: Save the PowerShell script as Sync_VMs.ps1 in C:\Program Files\SyncVM.

Edit the INI File: Open C:\Program Files\SyncVM\options.ini in a text editor and configure the settings as per your environment.

Run the Script: Open PowerShell as an Administrator and run the script:

powershell
Copy code
powershell -ExecutionPolicy Bypass -File "C:\Program Files\SyncVM\Sync_VMs.ps1"
Monitor the Progress: A progress box will appear, showing the VM currently being backed up and the overall progress.

Check Logs: Logs are saved in the directory specified by the LogPath setting in the .ini file. By default:

bash
Copy code
C:\HyperV\Logs\Backup_YYYYMMDD.log
Review Notifications: Email notifications will be sent upon completion, indicating success or failure.

INI File Parsing:

Reads all configurable settings (paths, retention, VMs, email) from the .ini file.
Validates required fields and provides defaults for optional fields.
Snapshot Retention:

Identifies snapshots older than the retention period and deletes them.
Backup Process:

Creates a checkpoint (snapshot) for each VM.
Uses RoboCopy to back up files from the local path to the remote path.
Removes the checkpoint after backup completion.
Progress Box:

Displays a GUI progress bar that updates with each VM.
Error Handling:

Logs errors and sends detailed error reports via email.

INI File Not Found: Ensure the .ini file exists at the specified path and is correctly formatted.

Hyper-V Cmdlets Not Found: Make sure the Hyper-V PowerShell module is installed.

Progress Box Does Not Appear: Verify that System.Windows.Forms is available in your PowerShell environment.

Email Fails to Send:

Check SMTP server, port, username, and password in the [Email] section of the .ini file.
Ensure the SMTP server allows relay from the machine running the script.
== Debugging Tips == Run the script in verbose mode:

powershell
Copy code
powershell -ExecutionPolicy Bypass -File "C:\Program Files\SyncVM\Sync_VMs.ps1" -Verbose
Review the log file for details on failures.

== Progress Box == The progress box will display the following:

diff
Copy code
VM Backup Progress
Processing VM: TestVM1
[========== ] 33%
== Email Notification == Example success email:

arduino
Copy code
Subject: [VM Backup] Backup Successful

The VM backup process completed successfully. Logs are attached.
Example failure email:

yaml
Copy code
Subject: [VM Backup] Backup Failed

The VM backup process encountered errors:
- Error processing VM: TestVM1 - Exception details here
- Error processing VM: TestVM2 - Exception details here

== Adjust RoboCopy Options == Modify the RoboOpts setting in the .ini file to customize the backup behavior. For example:

/MIR: Mirrors the source directory to the destination (deletes files not in the source).
/Z: Enables restartable mode.
/compress: Compresses data during transfer.
== Adding New VMs == Add new VMs under the [VMs] section in the .ini file:

ini
Copy code
[VMs]
VM4 = NewVM
VM5 = AnotherVM

Update INI File: Keep the .ini file updated with correct paths and VM names.
Log Review: Regularly review log files to ensure backups are successful.
Script Updates: Periodically review and update the script for compatibility with new PowerShell or Hyper-V versions.
yaml
Copy code

—

### Notes
- This DokuWiki content follows DokuWiki formatting conventions such as `======` for headings, `*` for bullet points, and `—-` for horizontal lines.
- Copy and paste the content directly into a DokuWiki page editor.

Let me know if you need further assistance!