Update documentation on VirtualBox drivers

This has minor cleanup of the documentation on VirtualBox
drivers. It fixes some grammatical issues and adds a bit more
clarification to some of the instructions for setting up a
developer's environment.

This is a follow up to I2018f9a89a3644863569ddac3126db71b125fb59.

Change-Id: I0f84554c98317160bfdfee14ba923cff4adda773
Implements: blueprint ironic-virtualbox-webservice-support

1 files changed, 50 insertions, 38 deletions

diff --git a/doc/source/drivers/vbox.rst b/doc/source/drivers/vbox.rst
index 1597ea844..b2e0c7ff9 100644
--- a/doc/source/drivers/vbox.rst
+++ b/doc/source/drivers/vbox.rst
@@ -7,38 +7,39 @@ VirtualBox drivers
 Overview
 ========
 
-VirtualBox drivers helps to use VirtualBox VMs as bare metals in Ironic.
+VirtualBox drivers can be used to test Ironic by using VirtualBox VMs to
+simulate bare metal nodes.
 
-Ironic has support in ``pxe_ssh`` and ``agent_ssh`` drivers for using a
-VirtualBox VM as a bare metal target and do provisioning on it. It works by
+Ironic provides support via the ``pxe_ssh`` and ``agent_ssh`` drivers for using
+a VirtualBox VM as a bare metal target and do provisioning on it. It works by
 connecting via SSH into the VirtualBox host and running commands using
 VBoxManage. This works well if you have VirtualBox installed on a Linux box.
 But when VirtualBox is installed on a Windows box, configuring and getting SSH
-to work with VBoxManage is a difficult (if not impossible) due to following
+to work with VBoxManage is difficult (if not impossible) due to the following
 reasons:
 
 * Windows doesn't come with native SSH support and one needs to use some
   third-party software to enable SSH support on Windows.
 * Even after configuring SSH, VBoxManage doesn't work remotely due to how
-  Windows manages user accounts - the native Windows user account is different
+  Windows manages user accounts -- the native Windows user account is different
   from the corresponding SSH user account, and VBoxManage doesn't work
-  properly when done with SSH user account.
-* Even after tweaking policies of VirtualBox application, the remote
+  properly when done with the SSH user account.
+* Even after tweaking the policies of the VirtualBox application, the remote
   VBoxManage and VBoxSvc don't sync each other properly and often results in
   a crash.
 
-VirtualBox drivers talk to VirtualBox web service running on the
-VirtualBox host using SOAP.  This is primarily intended for Ironic developers
-running Windows on their laptops/desktops (although they can be used on other
-operating systems as well).  These drivers enables the developers to configure
+VirtualBox drivers use SOAP to talk to the VirtualBox web service running on
+the VirtualBox host. These drivers are primarily intended for Ironic developers
+running Windows on their laptops/desktops, although they can be used on other
+operating systems as well.  Using these drivers, a developer could configure a
 cloud controller on one VirtualBox VM and use other VMs in the same VirtualBox
-as bare metals for the cloud controller.
+as bare metals for that cloud controller.
 
-Currently there three VirtualBox drivers are available :
+These VirtualBox drivers are available :
 
-* ``pxe_vbox`` - Uses iSCSI based deployment mechanism.
-* ``agent_vbox`` - Uses agent based deployment mechanism.
-* ``fake_vbox`` - Uses VirtualBox for power and management, but uses fake
+* ``pxe_vbox``: uses iSCSI-based deployment mechanism.
+* ``agent_vbox``: uses agent-based deployment mechanism.
+* ``fake_vbox``: uses VirtualBox for power and management, but uses fake
   deploy.
 
 
@@ -52,18 +53,20 @@ Setting up development environment
 
 * In VirtualBox Manager, Select ``cloud-controller`` VM -> Click Settings ->
   Network -> Adapter 2 -> Select 'Enable Network Adapter' ->
-  Select Attached to: Internel Network -> Select Name: intnet
+  Select Attached to: Internal Network -> Select Name: intnet
 
-* Create a VM in Oracle VirtualBox to act as bare metal. A VM with 1 CPU,
+* Create a VM in VirtualBox to act as bare metal. A VM with 1 CPU,
   1 GB memory should be sufficient. Let's name this VM as ``baremetal``.
 
 * In VirtualBox Manager, Select ``baremetal`` VM -> Click Settings ->
   Network -> Adapter 1 -> Select 'Enable Network Adapter' ->
-  Select Attached to: Internel Network -> Select Name: intnet
+  Select Attached to: Internal Network -> Select Name: intnet
 
-* Configure the VirtualBox web service to disable authentication (This is
-  only a suggestion, enable authentication if you want with appropriate
-  web service authentication library)::
+* Configure the VirtualBox web service to disable authentication. (This is
+  only a suggestion. If you want, enable authentication with the appropriate
+  web service authentication library.)
+
+  ::
 
     VBoxManage setproperty websrvauthlibrary null
 
@@ -71,12 +74,17 @@ Setting up development environment
 
     C:\Program Files\Oracle\VirtualBox\VBoxWebSrv.exe
 
-* Power on the ``cloud-controller`` VM, install GNU/Linux distribution of your
-  choice. Setup devstack on it.
+* Power on the ``cloud-controller`` VM.
+
+* All the following instructions are to be done in the ``cloud-controller`` VM.
+
+* Install the GNU/Linux distribution of your choice.
+
+* Set up devstack.
 
 * Install ZSI library.
 
-  On ubuntu::
+  On Ubuntu::
 
     sudo apt-get install python-ZSI
 
@@ -84,34 +92,38 @@ Setting up development environment
 
     sudo yum install python-ZSI
 
-* Install pyremotevbox on ``cloud-controller``::
+* Install pyremotevbox::
 
     sudo pip install pyremotevbox
 
-* Enable ``pxe_vbox`` or ``agent_vbox`` in ``enabled_drivers`` in
-  ``/etc/ironic/ironic.conf`` and restart Ironic conductor.
+* Enable one (or more) of the VirtualBox drivers (``pxe_vbox``, ``agent_vbox``,
+  or ``fake_vbox``) via the ``enabled_drivers`` configuration option in
+  ``/etc/ironic/ironic.conf``, and restart Ironic conductor.
 
-* Setup flat networking on ``eth1`` in ``cloud-controller``. Refer
+* Set up flat networking on ``eth1``. For details on how to do this, see
   :ref:`NeutronFlatNetworking`.
 
-* Enroll the VirtualBox node::
+* Enroll a VirtualBox node. The following examples use the ``pxe_vbox``
+  driver.
+
+  ::
 
     ironic node-create -d pxe_vbox -i virtualbox_host='10.0.2.2' -i virtualbox_vmname='baremetal'
 
-  If you are using authentication with VirtualBox web service, the Ironic
-  node-create looks like the below::
+  If you are using authentication with VirtualBox web service, your username
+  and password need to be provided. The ironic node-create command will look
+  like::
 
     ironic node-create -d pxe_vbox -i virtualbox_host='10.0.2.2' -i virtualbox_vmname='baremetal' -i virtualbox_username=<username> -i virtualbox_password=<password>
 
-  If VirtualBox web service is listening on another port (than the default
-  18083), then the VirtualBox port may be specified using the driver_info
+  If VirtualBox web service is listening on a different port than the default
+  18083, then that port may be specified using the driver_info
   parameter ``virtualbox_port``.
 
 * Add other Node properties and trigger provisioning on the bare metal node.
 
   .. note::
-    When booting a newly created VM for the first time, VirtualBox
-    automatically pops a dialog asking to 'Select start-up disk'. If
-    the baremetal VM is powered on for the first time by Ironic during
-    provisioning, this dialog will appear. Just press 'Cancel' to
+    When a newly created bare metal VM is powered on for the first time by
+    Ironic (during provisioning), VirtualBox will automatically pop up a
+    dialog box asking to 'Select start-up disk'. Just press 'Cancel' to
     continue booting the VM.