Introduction

VM Snapshots Help
Introduction
Introduction
Overview
Overview

VM Snapshots is a small application designed specifically to take periodic snapshots of a VirtualBox virtual machine. VM Snapshots allows a user to specify a time interval to leave between taking snapshots and the number of snapshots that are required, then leave VM Snapshots to automatically take the snapshots.

Taking snapshots of a virtual machine can be extremely useful for many reasons, as it allows a user to revisit a machine in the exact state that it was in at a certain point in time. VM Snapshots gives users the ability to revisit the state of their virtual machine at different incremental stages, without needing to take snapshots themselves. This is particularly useful in the case where a long running job has been left to run and the user anticipates needing to understand why that job behaved in a certain way at a certain time.

Requirements
Requirements

The application features a web based user interface which is powered by the Sciter engine, this is included in the installation.

VM Snapshots requires that VirtualBox has been installed and that a valid version of VBoxManage.exe is included within the VirtualBox installation; VM Snapshots executes the VBoxManage application in order to control virtual machines.


Version History

Version History
Version History
Summary
Summary

This page lists all versions of the application that have been released up until the version that this help file was release with; releases are listed newest first. The version numbers used for this application are made up of three parts : major, minor and maintenance, displayed in that order. The major version will be incremented if substantial changes are made to the application, the minor version will be incremented for smaller changes to the application, and the maintenance version will be incremented if the application is re-released in order to implement a bug fix.

1.0.0
1.0.0

18th March 2018

First version of the application.


Installation

Installation
Installation
Procedure
Procedure

The installation procedure for VM Snapshots will be similar to installation procedures for other Windows desktop applications. A Microsoft Installer (MSI) package file will be provided, and running the file will copy the required files to a user definable directory. The installation procedure will also offer to create a shortcut to the application. Note that installation of VM Snapshots on a network drive may cause problems when trying to display this help file.

Installation Files
Installation Files

Installation of VM Snapshots will result in a number of files being copied into the directory specified during the installation process :

  • sciter.dll - The Sciter engine that is used to display the user interface.

  • VBoxManage.exe - An demonstration application that can be used to simulate the output of VirtualBox's VBoxManage. This demonstration application simply produces output similar the VirtualBox's VBoxManage and nothing else.

  • VmSnapshots.chm - The VM Snapshots help document.

  • VmSnapshots.exe - The VM Snapshots application.

Uninstallation
Uninstallation

VM Snapshots can be uninstalled using the standard Windows "Add/Remove Programs" feature. Uninstallation will remove all the installation files listed above. Note that uninstalling VM Snapshots will not remove user specific configuration and error log files which may be created by the application. Configuration files will only be created if a user chooses to save their settings or chooses for settings to be saved when the application is closed. An error log file will only be created if an error occurs while a user is using the application. These files are left after uninstallation so that they can be used again should a user re-install the application in the future. It is safe to delete these files manually, either while the application is installed or after it has been uninstalled. These files can be found in the user's local application data folder in the subdirectories "\Andrew Griffiths\VM Snapshots". Typically, a user's local application data folder can be found in "C:\Users\user.name\AppData\Local\", therefore for a typical Windows installation files that will be left behind after uninstallation will be located at "C:\Users\user.name\AppData\Local\Andrew Griffiths\VM Snapshots".


Taking Snapshots

Taking Snapshots
Taking Snapshots
Locate VBoxManage.exe
Locate VBoxManage.exe

VM Snapshots interacts with VirtualBox using the VBoxManage executable supplied with VirtualBox installation. In order to use VBoxManage, VM Snapshots must know where it is located. This should be specified in the "Virtual Box Path" field (see Figure 1 below), usually Virtual Box installations are in the directory "C:\Program Files\Oracle\VirtualBox\".

Choose Virtual Machine
Choose Virtual Machine

After specifying the VBoxManage directory, VM Snapshots will search for any virtual machines that are attached and populate the "Virtual Machine Name" field (see Figure 1 below). Select the required virtual machine from the list of virtual machine names found.

Snapshots Prefix
Snapshots Prefix

When VM Snapshots takes a snapshot of a virtual machine, it will name the snapshot using the numeric value of the snapshot in the current snapshot sequence, for example, for a sequence of ten snapshots, snapshots will be named "1", "2", "3", ... "10". The snapshots prefix can be used to label the snapshots more meaningfully; VM Snapshots will name the snapshots "MyPrefix1", "MyPrefix2", etc...

Snapshots
Snapshots

Finally, the number of snapshots to take and the interval between snapshots must be specified. There are two numeric spinner inputs (see Figure 1 below) which allow these values to be input. Once all parameters have been specified, the snapshot sequence can be started by clicking the Take Snapshots button.

VM Snapshots Main Screen

Figure 1 - VM Snapshots Main Screen

Snapshots Sequence
Snapshots Sequence

The screenshot above displays the screens that should be used to set up snapshot sequences while the screenshots below show the screens that should be used to monitor the progress of snapshot sequences. Figure 1, the main screen of the application, is where the parameters described above should be specified. During the snapshots sequence, the screen shown in Figure 2 should provide information regarding the progress of the sequence. Whenever the application takes a snapshot, the screen shown in Figure 3 will appear. Note that it is not possible to cancel a snapshot while it is actually being taken (whenever the screen shown in Figure 3 is active). Upon successful completion of the snapshot sequence, a message should be displayed to confirm that the snapshot sequence has been completed (see Figure 4).

VM Snapshots Taking Snapshots Screen

Figure 2 - VM Snapshots Taking Snapshots Screen

VM Snapshots Taking Snapshot Screen

Figure 3 - VM Snapshots Taking Snapshot Screen

VM Snapshots Complete Screen

Figure 4 - VM Snapshots Sequence Complete Screen

Cancelling Snapshots
Cancelling Snapshots

Once a snapshot sequence has been initiated, it can be cancelled by clicking the Cancel button (see Figure 2 above). Any snapshots that have already been taken will be kept, but no further snapshots will be taken. It is not possible to cancel the sequence while a snapshot is actually being taken. If a snapshots sequence is cancelled a message should be displayed to confirm that the snapshot sequence has been cancelled (see Figure 5 below).

VM Snapshots Cancelled Screen

Figure 5 - VM Snapshots Sequence Cancelled Screen

Demonstration Application
Demonstration Application

Included in the installation is a "VBoxManage" executable. This is not VirtualBox's VBoxManage and will not provide any of the functionality that VirtualBox's VBoxManage program does. It simply produces output similar to the real VBoxManage program in order to demonstrate the functionality of VM Snapshots. If you point VM Snapshots to the VBoxManage executable provided with this installation, no snapshots will actually be taken.


Settings and Options

Settings and Options
Settings and Options
Configuration
Configuration

VM Snapshots uses an XML configuration file (saved in the user's local application data folder - see uninstallation) to store application settings and options, including snapshot sequence parameters. This therefore allows users to either save a particular configuration that is to be used frequently, or simply to save the last used configuration. The application configuration file is named "VmSnapshots.config" and is edited (or created if it does not exist already) when a user saves their settings or closes the application with the "Save on Exit" setting enabled. If the configuration file should become corrupted for any reason, it is safe to simply delete it and re-open the application.

Snapshots Parameters
Snapshots Parameters

Parameter that will be used to take the snapshots are specified on the main application screen :

  • Virtual Box Path - the path to the directory that contains the VBoxManage executable.

  • Virtual Machine Name - the name of the virtual machine for which snapshots are to be taken.

  • Snapshots Prefix - a prefix that will be prepended to a numeric value when naming each snapshot.

  • Number of Snapshots - the number of snapshots to take.

  • Snapshots Interval - the time to leave in between taking each snapshot, specified in seconds.

Settings
Settings

The Settings screen can be accessed by clicking on the gear symbol in the top right of the main screen of the application, doing so will open the screen shown in Figure 6.

VM Snapshots Settings Screen

Figure 6 - VM Snapshots Settings Screen

The Settings screen allows users to change the way in which the application will behave :

  • Save on Exit - when this option is enabled, the application will save the current snapshot configuration whenever the application is closed, so that the last used settings are available the next time that the application is used.

  • Delay First Snapshot - when this option is enabled the first snapshot will not be taken until the specified interval has elapsed, otherwise the first snapshot will be taken immediately.

  • Snapshot Timeout - when taking a snapshot, the application will wait for VBoxManage to respond before continuing the snapshot sequence. This value, specified in seconds, determines the maximum time that VM Snapshots will wait for VBoxManage to respond. If the timeout elapses, the current snapshot and snapshot sequence will be abandoned.


Support

Support
Support
Summary
Summary

While every attempt has been made to ensure that the software functions as intended, and the software has been tested during and after development, it is still possible that there exist inaccuracies or bugs. Should the need arise, the contact details below can be used to request support or notify support of an issue.

Error Log
Error Log

In the case of an error occurring the application will attempt to create an error log file in the user's local application directory (typically "C:\Users\user.name\AppData\Local\Andrew Griffiths\VM Snapshots"), named "Error.log". If you request support regarding an application error, please also send a copy of the error log file.

Contact
Contact

support@andrewgriffiths.eu

andrewgriffiths.eu/vmsnapshots


Licence Information

Licence Information
Licence Information
Licences
Licences

This product uses third party products which are licensed under their own licence agreements. The third party products used in this product are Sciter and RapidXML, licences under which each third party product is issued are included in this help document, as well as the licence under which VM Snapshots itself is issued. In addition, a copy of each licence file can be found both in the application install directory and in the "about" window in the application itself. VM Snapshots is not endorsed by any third party product of which it makes use.

All files distributed as part of this product, with the exception of the "sciter.dll" file, which is subject to its own end user licence agreement, are licensed under the MIT licence. By installing and using this product you are agreeing to the terms of the licence agreements.

A copy of the licence agreement for each product can be found by following the links below.

  • VM Snapshots Licence Agreement

  • Sciter Licence Agreement

  • RapidXML Licence Agreement


VM Snapshots Licence Agreement

VM Snapshots Licence Agreement
VM Snapshots Licence Agreement

All files distributed as part of this product, with the exception of the "sciter.dll" file, which is subject to its own end user licence agreement, are licensed under the MIT licence, which is stated below.

The MIT Licence
The MIT Licence

Copyright © 2018 Andrew Griffiths

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


Sciter Licence Agreement

Sciter Licence Agreement
Sciter Licence Agreement

VM Snapshots uses the Sciter Engine which is licensed under its own end user licence agreement, stated below. Specifically the "sciter.dll" file which is distributed with VM Snapshots is licensed under this licence agreement.

Sciter Engine ™ Software Product
Sciter Engine ™ Software Product
End User Licence Agreement
End User Licence Agreement

This End User License Agreement is not a sales contract but an agreement between Terra Informatica Software, Inc. and you regarding the use of the software - the Sciter. Installing this software implies that you agree to the terms of this agreement. If you disagree with any part of this license agreement, do not install the software.

"Sciter Engine Software Product" shall mean one of sciter.dll, sciter.dylib and sciter.so - dynamically linked library (DLL) that contain embeddable Sciter Engine, the software programs and files needed to integrate the Sciter Engine with a software application, including documentation, examples, include files, declarations, source code, utility programs, and libraries.

1. RIGHT TO USE THE SOFTWARE

Terra Informatica Software, Inc. gives you the right to use this software in accordance with the terms of this agreement.

You may utilize sciter dll in any manner you see fit (subject to the limitations outlined in this license) to build commercial or non-commercial applications and components.

Your application shall include link to Terra Informatica site in "About" dialog or similar place in your application. Text of the link: This Application (or Component) uses Sciter Engine (http://sciter.com/), copyright Terra Informatica Software, Inc.

We will be delighted (but not demand) if you will place link to http://sciter.com/ on the web page of your product using the Sciter.

2. COPYRIGHT

The copyright and intellectual property rights of this software and its documentation and packaging are owned by Terra Informatica Software, Inc. and are protected by the copyright laws of Canada and international intellectual property right treaties.

3. LIMITATION OF WARRANTY

Trying to satisfy your needs as much as possible Terra Informatica Software, Inc. does not warrant though that using this software will fit a user's particular purpose, and is not liable for any damages caused by the use of this software.

4. ACKNOWLEDGEMENT

You acknowledge that you have read and understand this license agreement and that you agree to its terms. You acknowledge that this agreement has priority over any order, engagement, advertisement, or other written agreement which precedes it.

Terra Informatica Software, Inc. © 2006-2017, all rights reserved.


RapidXML Licence Agreement

RapidXML Licence Agreement
RapidXML Licence Agreement

No RapidXML files are distributed with VM Snapshots, however VM Snapshots makes use of RapidXML and in accordance with the terms under which RapidXML is licensed, the RapidXML licence agreement is stated below.

RapidXML is licensed under one of the following two licences, to be chosen freely by the user.

1. Boost Software License - Version 1.0 - August 17th, 2003
1. Boost Software License - Version 1.0 - August 17th, 2003

Copyright © 2006, 2007 Marcin Kalicinski

Permission is hereby granted, free of charge, to any person or organization obtaining a copy of the software and accompanying documentation covered by this license (the "Software") to use, reproduce, display, distribute, execute, and transmit the Software, and to prepare derivative works of the Software, and to permit third-parties to whom the Software is furnished to do so, all subject to the following:

The copyright notices in the Software and this entire statement, including the above license grant, this restriction and the following disclaimer, must be included in all copies of the Software, in whole or in part, and all derivative works of the Software, unless such copies or derivative works are solely in the form of machine-executable object code generated by a source language processor.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

2. The MIT License
2. The MIT License

Copyright © 2006, 2007 Marcin Kalicinski

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.