Differences

This shows you the differences between two versions of the page.

--- backupmanagement [2024/12/30 23:44] – Darren
+++ backupmanagement [2024/12/30 23:47] (current) – old revision restored (2024/12/25 10:57) Darren
@@ Line 1: / Line 1: @@
-====== VM Backup and Snapshot Retention Script ======
+====== User Guide for VM Backup and Snapshot Retention Script ======
-=== Purpose ===\\
+=== Overview ===
-This PowerShell script automates the process of:\\
+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.
-* 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 ===\\
+==== Features ====
-* **INI-Based Configuration**: All settings, including email and paths, are configured via an easy-to-edit `.ini` file.\\
+  * Automated VM snapshot creation.
-* **Snapshot Retention**: Removes old snapshots based on the retention period defined in the `.ini` file.\\
+  * Retention management for old snapshots.
-* **Automated Backup**: Uses `RoboCopy` to back up VM files to a remote or local destination.\\
+  * Configurable backup paths and options.
-* **Email Notifications**: Notifies the user of the script's success or failure.\\
+  * Dynamic inclusion of VMs via the INI file.
-* **Progress Box**: Displays a Windows-like GUI progress bar during the backup process.
+  * Detailed logging of operations.
+  * Fully customizable through an easy-to-use configuration file.
 ----
-=== Prerequisites ===\\
+=== Prerequisites ===
-- **PowerShell Version**: Ensure PowerShell 5.1 or later is installed.\\
+  - **System Requirements:**
-- **Hyper-V Module**: The script uses `Checkpoint-VM`, `Get-VMSnapshot`, and `Remove-VMSnapshot`. The Hyper-V PowerShell module must be installed.\\
+    * Windows Server or Windows 10/11 with Hyper-V installed.
-- **INI File Configuration**: The script relies on an `.ini` file for settings.\\
+    * PowerShell 5.0 or later.
-- **Windows Forms Assembly**: The script uses `System.Windows.Forms` for the progress box. This is included by default on Windows.
-----
+  - **Required Permissions:**
+    * Administrative privileges to manage VMs and access file paths.
-=== Configuration ===
+  - **Dependencies:**
+    * ''RoboCopy'' (built into Windows).
-== INI File ==\\
+  - **Configuration File:**
-The script uses an `.ini` file located at:\\
+    * A properly formatted INI file must be created and configured.
-* **`C:\Program Files\SyncVM\options.ini`**
-Below is an example `.ini` file with all available settings:
+----
-```ini\\
+=== Configurable Options ===
-[Settings]\\
+All configurations are stored in the ''options.ini'' file.
-RetentionDays = 7 ; Number of days to retain snapshots\\
-LocalPath = C:\HyperV\VMs ; Local directory where VM files are stored\\
-RemotePath = [[\\BackupServer\Backups|\\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]\\
+==== Example INI File ====
-VM1 = TestVM1\\
+<code ini>
-VM2 = TestVM2\\
+[Settings]
-VM3 = TestVM3
+RetentionDays = 7
+LocalPath = C:\VMBackups
+RemotePath = \\BackupServer\VMs
+LogPath = C:\VMLogs
+RoboOpts = /MIR /e /FFT /Z /XA:H /W:5 /compress
-[Email]\\
+[VMs]
-To = admin@example.com ; Email address to send notifications to\\
+VM1 = MyVirtualMachine1
-From = backup@example.com ; Email address to send notifications from\\
+VM2 = MyVirtualMachine2
-SMTPServer = smtp.example.com ; SMTP server for sending email\\
+VM3 = MyVirtualMachine3
-SMTPPort = 587 ; SMTP port (e.g., 587 for TLS, 25 for standard)\\
+</code>
-SMTPUsername = username@example.com ; Username for SMTP authentication\\
-SMTPPassword = yourpassword ; Password for SMTP authentication\\
-SubjectPrefix = [VM Backup] ; Prefix for email subject lines
-== Explanation of INI File Sections ==
+==== Sections and Parameters ====
+  - **[Settings]**
+    - **RetentionDays**: Number of days to retain snapshots before deletion. Older snapshots will be automatically removed.
+      - **Default:** ''7''
+      - **Example:** ''RetentionDays = 14''
-[Settings]:
+    - **LocalPath**: Local directory where the VM files are stored.
+      - **Example:** ''LocalPath = C:\VMBackups''
-RetentionDays: How long (in days) to retain VM snapshots.\\
+    - **RemotePath**: Remote destination directory for backups. Use UNC paths for network locations.
-LocalPath: Directory containing VM files.\\
+      - **Example:** ''RemotePath = \\BackupServer\VMs''
-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.\\
+    - **LogPath**: Directory where log files will be saved.
-[Email]:
+      - **Example:** ''LogPath = C:\VMLogs''
-SMTP settings for sending email notifications.\\
+    - **RoboOpts**: Customizable options for RoboCopy. These should be formatted as a single string of space-separated options.
-Authentication is optional; if omitted, the script attempts to send emails without it.\\
+      - **Default:** ''/MIR /e /FFT /Z /XA:H /W:5 /compress''
-=== Script Usage ===
+      - **Example:** ''RoboOpts = /S /ZB /R:3''
-== Steps to Run the Script ==
+  - **[VMs]**
+    - 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.
+      - **Example:**
+<code ini>
+[VMs]
+VM1 = MyVirtualMachine1
+VM2 = MyVirtualMachine2
+VM3 = MyVirtualMachine3
+</code>
-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.
+=== Script Functionality ===
-Run the Script: Open PowerShell as an Administrator and run the script:
+==== Key Components ====
+  - **Snapshot Management**
+    - The script creates a snapshot for each VM listed in the INI file.
+    - Old snapshots are removed based on the retention period defined in the ''RetentionDays'' parameter.
-powershell\\
+  - **Backup Process**
-Copy code\\
+    - The script uses RoboCopy to transfer VM files from the ''LocalPath'' to the ''RemotePath''.
-powershell -ExecutionPolicy Bypass -File "C:\Program Files\SyncVM\Sync_VMs.ps1"\\
+    - Configurable options for RoboCopy allow fine-tuning of backup behavior.
-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:
+  - **Logging**
+    - All operations are logged in a file created in the directory specified by ''LogPath''.
+    - Log entries include timestamps and descriptions of actions performed.
-bash\\
+----
-Copy code\\
-C:\HyperV\Logs\Backup_YYYYMMDD.log\\
-Review Notifications: Email notifications will be sent upon completion, indicating success or failure.
-=== How It Works ===
+=== How to Use ===
-INI File Parsing:
+==== Step 1: Configure the INI File ====
+. Open the ''options.ini'' file in a text editor.
+. Modify the parameters in the ''[Settings]'' and ''[VMs]'' sections as needed.
+. Save the file.
-Reads all configurable settings (paths, retention, VMs, email) from the .ini file.\\
+==== Step 2: Run the Script ====
-Validates required fields and provides defaults for optional fields.\\
+. Open a PowerShell window with administrative privileges.
-Snapshot Retention:
+. Navigate to the directory containing the script.
+. Execute the script:
+<code powershell>
+.\BackupScript.ps1
+</code>
+. The script will automatically read the ''options.ini'' file, process VMs, and log the operations.
-Identifies snapshots older than the retention period and deletes them.\\
+==== Step 3: Review Logs ====
-Backup Process:
+  * Check the log files in the directory specified by ''LogPath'' for details of the 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.\\
 === Troubleshooting ===
-== Common Issues ==
+==== Common Errors and Solutions ====
+  - **Error:** "Invalid Parameter #3"
+    - **Cause:** RoboCopy options are not split correctly.
+    - **Solution:** Ensure ''RoboOpts'' in the INI file is a valid string of space-separated options.
-INI File Not Found: Ensure the .ini file exists at the specified path and is correctly formatted.
+  - **Error:** "Access Denied"
+    - **Cause:** Insufficient permissions to access VM files or remote path.
+    - **Solution:** Run PowerShell as an administrator and verify permissions for the specified directories.
-Hyper-V Cmdlets Not Found: Make sure the Hyper-V PowerShell module is installed.
+  - **Error:** "VM not found"
+    - **Cause:** VM name in the INI file does not match an existing VM.
+    - **Solution:** Verify the VM names in the ''[VMs]'' section of the INI file.
-Progress Box Does Not Appear: Verify that System.Windows.Forms is available in your PowerShell environment.
+----
-Email Fails to Send:
+=== Advanced Usage ===
-Check SMTP server, port, username, and password in the [Email] section of the .ini file.\\
+==== Customizing RoboCopy Options ====
-Ensure the SMTP server allows relay from the machine running the script.\\
+  - The ''RoboOpts'' parameter allows you to customize the behavior of RoboCopy.
-== Debugging Tips == Run the script in verbose mode:
+  - Example Options:
+    - ''/MIR'': Mirrors the directory structure.
+    - ''/Z'': Enables restartable mode for interrupted transfers.
+    - ''/XA:H'': Excludes hidden files.
+    - ''/R:N'': Specifies the number of retry attempts.
-powershell\\
+==== Adding or Removing VMs ====
-Copy code\\
+  - **To add a VM:**
-powershell -ExecutionPolicy Bypass -File "C:\Program Files\SyncVM\Sync_VMs.ps1" -Verbose\\
+. Add a new entry in the ''[VMs]'' section of the INI file.
-Review the log file for details on failures.
+       - Example: ''VM4 = MyVirtualMachine4''
+. Save the INI file.
-=== Example Output ===
+  - **To remove a VM:**
+. Delete the corresponding entry in the ''[VMs]'' section.
+. Save the INI file.
-== Progress Box == The progress box will display the following:
+----
-diff\\
+=== Maintenance and Updates ===
-Copy code\\
+  - **Log Management:** Periodically clean up old logs in the ''LogPath'' directory to save space.
-VM Backup Progress\\
+  - **INI File Updates:** Review and update the INI file as necessary to reflect changes in the VM environment.
-Processing VM: TestVM1\\
+  - **Script Updates:** Check for script updates to ensure compatibility with the latest systems and features.
-[==========             ] 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\\
-=== Advanced Configuration ===
-== 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\\
-=== Maintenance ===
-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!
+=== Contact and Support ===
+For questions or issues, please contact the script author or system administrator.