Merge remote-tracking branch 'pf/pf-document-extensions'

Reviewed-by: Richard Maw
Reviewed-by: Pete Fotheringham

2 files changed, 30 insertions, 28 deletions

diff --git a/morphlib/exts/kvm.write b/morphlib/exts/kvm.write
index 16f188b5..61c96676 100755
--- a/morphlib/exts/kvm.write
+++ b/morphlib/exts/kvm.write
@@ -30,40 +30,20 @@ import morphlib.writeexts
 
 class KvmPlusSshWriteExtension(morphlib.writeexts.WriteExtension):
 
-    '''Create a KVM/LibVirt virtual machine during Morph's deployment.
-    
-    The location command line argument is the pathname of the disk image
-    to be created. The user is expected to provide the location argument
-    using the following syntax:
-    
-        kvm+ssh://HOST/GUEST/PATH
-        
-    where:
-    
-    * HOST is the host on which KVM/LibVirt is running
-    * GUEST is the name of the guest virtual machine on that host
-    * PATH is the path to the disk image that should be created,
-      on that host
-  
-    The extension will connect to HOST via ssh to run libvirt's
-    command line management tools.
-    
-    '''
-
     location_pattern = '^/(?P<guest>[^/]+)(?P<path>/.+)$'
 
     def process_args(self, args):
         if len(args) != 2:
             raise cliapp.AppException('Wrong number of command line args')
-        
+
         temp_root, location = args
         ssh_host, vm_name, vm_path = self.parse_location(location)
         autostart = self.get_environment_boolean('AUTOSTART')
-        
+
         fd, raw_disk = tempfile.mkstemp()
         os.close(fd)
         self.create_local_system(temp_root, raw_disk)
-        
+
         try:
             self.transfer(raw_disk, ssh_host, vm_path)
             self.create_libvirt_guest(ssh_host, vm_name, vm_path, autostart)
@@ -105,7 +85,7 @@ class KvmPlusSshWriteExtension(morphlib.writeexts.WriteExtension):
 
     def create_libvirt_guest(self, ssh_host, vm_name, vm_path, autostart):
         '''Create the libvirt virtual machine.'''
-        
+
         self.status(msg='Creating libvirt/kvm virtual machine')
 
         attach_disks = self.parse_attach_disks()
@@ -135,4 +115,3 @@ class KvmPlusSshWriteExtension(morphlib.writeexts.WriteExtension):
                 ['virsh', '--connect', 'qemu:///system', 'autostart', vm_name])
 
 KvmPlusSshWriteExtension().run()
-
diff --git a/morphlib/exts/kvm.write.help b/morphlib/exts/kvm.write.help
index 8b5053a5..ad0e25f0 100644
--- a/morphlib/exts/kvm.write.help
+++ b/morphlib/exts/kvm.write.help
@@ -1,4 +1,27 @@
 help: |
-    The INITRAMFS_PATH option can be used to specify the location of an
-    initramfs for syslinux to tell Linux to use, rather than booting
-    the rootfs directly.
+
+    Create a KVM/LibVirt virtual machine during Morph's deployment.
+
+    Parameters:
+
+    * location: a custom URL scheme of the form `kvm+ssh://HOST/GUEST/PATH`,
+      where:
+        * HOST is the name of the host on which KVM/LibVirt is running
+        * GUEST is the name of the guest VM on that host
+        * PATH is the path to the disk image that should be created,
+          on that host. For example,
+          `kvm+ssh://alice@192.168.122.1/testsys/home/alice/testys.img` where
+            * `alice@192.168.122.1` is the target host as given to ssh,
+              **from within the development host** (which may be
+              different from the target host's normal address);
+            * `testsys` is the name of the new guest VM';
+            * `/home/alice/testys.img` is the pathname of the disk image files
+              on the target host.
+    * HOSTNAME: the hostname of the **guest** VM within the network into which
+      it is being deployed
+    * DISK_SIZE: the size of the VM's primary virtual hard disk
+    * RAM_SIZE: The amount of RAM that the virtual machine should allocate for
+      itself from the host.
+    * VCPUS: the number of virtual CPUs for the VM
+    * INITRAMFS_PATH: the location of an initramfs for the bootloader to tell
+      Linux to use, rather than booting the rootfs directly.