Getting Started – VirtualBox and HistoryCrawler

This selective introduction to VirtualBox and HistoryCrawler is written as a reference for William J Turkel’s course, History 9877A: Digital Research Methods, offered by the Department of History at Western University.  It is written for OS X hosts, but should also serve as a general guide for Windows hosts.

Starting HistoryCrawler in VirtualBox – 
See Chapter 1. First Steps of the VirtualBox Manual, specifically Section 1.8. Running your virtual machine.

  1. Open Oracle VirtualBox on your host machine.
  2. In the Oracle VM VirtualBox Manager window select the virtual machine you wish to open from the list on the left.
  3. After selecting the appropriate virtual machine from the list, click the ‘Start’ button at the top of the Oracle VM VirtualBox Manager window OR double-click the appropriate virtual machine in the list on the left.Oracle VM VirtualBox Manager

Note: The following error message will appear when you start HistoryCrawler.  If you do not plan to use a shared folder ignore this message.  If you want to fix this error see the ‘Sharing Files with HistoryCrawler by Creating a Shared Folder’ section below.Error Message

Stopping HistoryCrawler in VirtualBox – 
See Chapter 1. First Steps of the VirtualBox Manual, specifically see Section 1.8.6. Saving the state of the machine.

When closing the HistoryCrawler window a VirtualBox window will pop up offering three options for stopping the virtual machine.Stopping the HistoryCrawler

  • Saving the machine state – this option will freeze your virtual machine.  The next time the virtual machine is started it will be exactly as it was left (programs will be open, etc.).
  • Send the shutdown signal – this option is similar to pressing the power button on a real computer.
  • Power off the machine – this option is similar to pulling the cord on a real computer without shutting it down properly.  This should not be done unless you wish to restore the current snapshot of the virtual machine (see the ‘Taking Snapshots of HistoryCrawler’ section below).
  1. Select the stopping option that best suits your needs.
  2. Click ‘OK’.

Taking Snapshots of HistoryCrawler – 
See Chapter 1. First Steps of the VirtualBox Manual, specifically Section 1.10. Snapshots.

Snapshots can be taken when the virtual machine is running OR when the virtual machine is in saved or powered off state.

If the virtual machine is running:

  1. In the menu bar click on ‘Machine’.
  2. Select ‘Take a Snapshot’.

If the virtual machine is in either saved or powered off state:

  1. In the Oracle VM VirtualBox Manager window select the virtual machine of which you would like a snapshot.
  2. Click the ‘Snapshots’ tab at the top right.
  3. Click the ‘Camera’ icon OR right-click ‘Current State’ and select ‘Take a Snapshot’.

At this point (no matter whether the virtual machine is running, saved, or powered off) a window will pop up:Snapshot

  1. Under ‘Snapshot Name’ give your snapshot a name.  The purpose of naming the snapshot is to help you remember the state of the machine when the snapshot was taken.
  2. Under ‘Snapshot Description’ you can include more detail about the machine state.
  3. Click ‘OK’ and your snapshot will now appear in your list of snapshots.

Note: there is no limit to the number of snapshots you can take; however, each snapshot will occupy some disk space on your host machine.

Restore a Snapshot of HistoryCrawler – 
See Chapter 1. First Steps of the VirtualBox Manual, specifically Section 1.10. Snapshots.

  1. In the Oracle VM VirtualBox Manager window select the virtual machine of which you would like to restore a snapshot.
  2. Click the ‘Snapshots’ tab at the top right.
  3. Right-click on the snapshot you wish to restore and select ‘Restore Snapshot’.

Note: restoring a snapshot will result in the current state of the virtual machine being lost (this includes any files that have been created).  VirtualBox will prompt you to take a snapshot of the current state of your virtual machine prior to restoring a previous snapshot.Restore Snapshot

Delete a Snapshot of HistoryCrawler – 
See Chapter 1. First Steps of the VirtualBox Manual, specifically Section 1.10. Snapshots.

  1. In the Oracle VM VirtualBox Manager window click on the virtual machine of which you wish to delete a snapshot.
  2. Click the ‘Snapshots’ tab at the top right.
  3. Right-click the snapshot you wish to delete and select ‘Delete Snapshot’

Note: your virtual machine may need to be shutdown to delete a snapshot.

Opening a Terminal in HistoryCrawler’s GUI –

  1. Click on the Kickoff menu at the top left.
  2. Click on ‘Terminal’.

Opening Atom (an-easier-to-use-than-vi editor) in HistoryCrawler’s GUI –

  1. Click on the Kickoff menu.
  2. Go to ‘Applications’.
  3. Click on ‘Utilities’.
  4. Click on ‘Atom‘.

Using Atom to Create and Save Files in HistoryCrawler’s GUI –

  1. Open Atom in HistoryCrawler’s GUI.
  2. Type desired content into Atom.
  3. Under File menu click ‘Save As’ and a Save File window will pop up.Atom - Save File window
  4. In the ‘Places’ field select ‘hcu’.
  5. In the ‘Name’ field type desired filename and remember to include the appropriate file extension (for example, .txt).

Using Atom to Create and Save Files in a Terminal in HistoryCrawler – 

  1. Open a terminal.
  2. At the command line type – atom filename.appropriatefileextension (for example, atom test.txt).atom test.txt
  3. Type desired content into Atom.
  4. Under File menu click ‘Save’.
  5. After saving your file, close Atom.
  6. Use the ls command to make sure that the file is listed in the home directory.

Note: when using Atom to create and save files in a terminal, the file will be saved to the same directory within which Atom was opened.  For example, if Atom is opened in the home directory the file created will be saved to the home directory (unless specified otherwise using ‘Save As’). Likewise, if Atom is opened in the Documents directory the file created will be saved to the Documents directory.

Sharing Files with HistoryCrawler by Dragging and Dropping – 

  1. Select the file or files on your host machine that you wish to share with HistoryCrawler.
  2. Drag the file/files into the running HistoryCrawler window and drop.
  3. The file/files may or may not display as a shortcut on HistoryCrawler’s desktop.
  4. To locate the dropped file/files click on the Kickoff menu.
  5. Click on ‘File Manager‘.
  6. In the file manager click on the ‘Documents’ folder, then click on the ‘VirtualBox Dropped Files’ folder.  In the ‘VirtualBox Dropped Files’ folder there will be a folder named with a specific date and time.  In this folder you will find the dropped file/files.Drag and Drop File

Note: you may wish to move or copy your dropped file/files to Home so that they are more directly accessible (located in the home directory) when using a terminal.  To do this, you can copy and paste the file/files to Home OR you can move the file/files to Home by dragging and dropping.

Sharing Files with HistoryCrawler by Creating a Shared Folder – 
Note: The virtual machine must be powered off before attempting to create a shared folder.

  1. On your host machine create a folder for sharing files between the host machine and the virtual machine.  For example, you may call this folder vm-shared.
  2. In the Oracle VM VirtualBox Manager window select the virtual machine for which you wish to create a shared folder.  In this case, select HistoryCrawler.
  3. Under the ‘Details’ tab scroll down and double-click on ‘Shared Folders’.
  4. The Shared Folders window will pop up.  In HistoryCrawler you will see that a shared folder already exists; however, it is necessary to create a shared folder for your specific host machine.Shared Folders Window
  5. Click the ‘Add’ icon.
  6. The Add Share window will pop up.  Under the ‘Folder Path’ field click the drop down arrow and select ‘Other’.Add Share Window
  7. The host machine’s file manager will pop up.  Select the folder you created on your host machine (for example, vm-shared) and click ‘Choose’.
  8. In the Add Share window the name of the folder you created on your host machine will appear in the ‘Folder Name’ field.  Check the box beside ‘Auto-mount’ and click ‘OK’.Add Share Window (vm-shared)
  9. In the Shared Folders window click ‘OK’.
  10. In the Oracle VM VirtualBox Manager window click ‘Shared Folders’ again.  You will now see two shared folders in the Shared Folders window.Shared Folders Window (2 shared folders)
  11. Select the first shared folder in the list (shared-folder /User/wjt/VirtualBox VMs/shared-folder) and click the ‘Remove’ icon.  Click ‘OK’.

Note: when you start HistoryCrawler your new shared folder will be located in Root/Media/sf_vm-shared OR Root/Media/sf_whateveryounamedyoursharedfolder.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s