update README.txt
authorJens Kasten <jens@kasten-edv.de>
Sat, 07 Apr 2012 16:38:10 +0200
changeset 112 0ca5084026ff
parent 111 858636a26627
child 113 d180b27d13a9
update README.txt
README.txt
bin/kvm-admin
kvmtools/config/kvm_parser.py
kvmtools/header.py
kvmtools/kvm/action.py
--- a/README.txt	Sat Mar 31 04:53:40 2012 +0200
+++ b/README.txt	Sat Apr 07 16:38:10 2012 +0200
@@ -1,38 +1,28 @@
 =========
 kvm-tools
 =========
-Depend on Python version >= 2.4 and < 3.0
-
-A commandline script to use a simple guest configuration file.
+A commandline script to use a simple domain(guest) configuration file.
 
-usage: kvm-admin [-h]
-                 domain_name
+usage: kvm-admin [-h] [--debug]
                  {boot,create,kill,modify,monitor,reboot,show,shutdown,status}
-                 [option [option ...]]
+                 ...
 
 optional arguments:
   -h, --help            show this help message and exit
+  --debug               Print full python traceback.
 
-QEMU-KVM domain:
-  domain_name           Choose a KVM domain name, its the same like the
-                        configuration file name
+All commands for kvm-admin:
+  valid kvm-admin commands
 
-Action for a domain:
   {boot,create,kill,modify,monitor,reboot,show,shutdown,status}
-                        Choose an action for the KVM guest
-
-Monitor command:
-  option                One ore more arguments can pass to the monitor.
-
-usage: kvm-admin [-h] [--generate-options]
-                 kvm_guest_name action [monitor [monitor ...]]
+                        additional help
 
 =========
 Depencies
 =========
 List: python >=2.4 and < 3.0 
       python-argparse (debian package name)
-        optional using argparse from kvmtools.config.argparse 
+        optional using argparse from kvmtools.argparse 
 
 
 All others are standard python library.
@@ -40,12 +30,10 @@
 ======
 Update
 ======
-When qemu-kvm change or add parameter, than the this run this command:
-	generate-kvm-options --generate
+When you update qemu-kvm than run this command:
+	generate-kvm-options --generate --verbose
 
-# Fix: and a config with current qemu-kvm verion and compare it each run
-
-This build a new list of all availables qemu-kvm options.
+This build a list of all availables qemu-kvm options.
 This is used to check if the given key in the configuration file 
 is a valid qemu-kvm option.
 
@@ -60,7 +48,7 @@
 ========
 1. The scripts can downloaded via webrowser as bz2, zip, or gzip archive.
 	http://hg.kasten-edv.de/kvm-tools
-	https://hg.kasten-edv.de/kvm-tools --insecure
+	https://hg.kasten-edv.de/kvm-tools 
 
 2. clone the mercurial repository. 
     hg clone http://hg.kasten-edv.de/kvm-tools  
@@ -77,18 +65,20 @@
 ==================
 Its recommend to use an unprivileged user.
 It can set in the global configuration file /etc/kvm/config/kvm.cfg
+
 Uncomment:
 	# optional, add an user kvm to run the qemu-kvm process
 	runas = kvm
 
-Each guest configuration file can have this option too.
+Each domain configuration file can have this option too to use for each domain 
+a different user.
 
-Example to use a system user kvm on debian. 
-If qemu-kvm already is installed,then add only the group kvm
+Example to use an system user kvm on debian. 
+If qemu-kvm already is installed then add only the group kvm
 and modify the /etc/passwd.
 
-	addgroup --gid 116 kvm_test
-	adduser --system --gid 116 --uid 116 --home /var/run/kvm_test --disabled-password --shell /bin/false kvm
+	addgroup --gid 116 kvm
+	adduser --system --gid 116 --uid 116 --home /var/run/kvm --disabled-password --shell /bin/false kvm
 	chown kvm:kvm /var/run/kvm  (or /usr/local/var/run/kvm)
     chmod 750 /var/run/kvm  (or /usr/local/var/run/kvm)
 
@@ -106,7 +96,7 @@
 ===================
 Guest configuration
 ===================
-An example for a domain(guest) configuration file.
+An example for a domain configuration file.
 The syntax values are 1:1 on commandline usage the only differ is instead using
 	-option_name value
 	option_name = value
@@ -128,7 +118,7 @@
 Example domain configuration file:
     name = my_first_domain
     # first drive
-    drive = file=/home/kvm/my_testfile.img,if=virtio,index=0,boot=on,cache=none
+    drive = file=/home/kvm/my_testfile.img,if=virtio,index=0,cache=none
     # second drive 
     drive = file=/home/kvm/my_swapfile.img,if=virtio,index=1,cache=none
     # memory for using in the guest
@@ -165,6 +155,15 @@
     # optinal, run as kvm user
     runas = kvm
 
+================
+Sound for guests
+================
+You have to do this as root user:
+    modprobe -v snd-pcm-oss
+Or:
+    export QEMU_AUDIO_DRV=alsa 
+
+
 ====================
 Hotplug a pci device
 ====================
@@ -183,12 +182,11 @@
 =============
 You can communicate with the guest monitor on commandline.
 Each command behind the monitor concatenate to a string. 
-No quotations are needed.
 
-usage: kvm-admin domain_name monitor help
+usage: kvm-admin monitor domain_name option
 
 Reboot or shutdown or status can send via the monitor too.
-    kvm-admin domain_name monitor system_powerdown
+    kvm-admin monitor domain_name system_powerdown
 
 You can use the command line monitor like the orgin "ALT + CTRL + 2" monitor.
 You can add an usb device or ecject cdrom etc.
--- a/bin/kvm-admin	Sat Mar 31 04:53:40 2012 +0200
+++ b/bin/kvm-admin	Sat Apr 07 16:38:10 2012 +0200
@@ -56,7 +56,6 @@
         # load the methods which are available for doamin
         Action.__init__(self)
         self.value = None
-        self.debug = False
 
     def run(self):
         """Do an action for a domain.
@@ -65,12 +64,9 @@
         kvm_method = "".join(["kvm_", self.action, "_action"])
         self.monitor_open()
         if "monitor" in self.action or "migrate" in self.action:
-            if self.monitor:
-                # build string from third option till end
-                cmd_monitor = " ".join(str(i) for i in self.monitor)
-                getattr(self, kvm_method)(cmd_monitor)
-            else:
-                raise Exception("Missing monitor argument. Type 'help'.")
+            # build string from third option till end
+            cmd_monitor = " ".join(str(i) for i in self.monitor)
+            getattr(self, kvm_method)(cmd_monitor)
         else:
             getattr(self, kvm_method)()
         self.monitor_close()
@@ -97,39 +93,55 @@
     domains = kvm_admin.available_domains()
 
     # manage the commandline arguments
-    parser = argparse.ArgumentParser(
-        epilog="Available domains: %s" % ", ".join(domains))
+    parser = argparse.ArgumentParser()
     parser.add_argument("--debug", default=False, action="store_true",
-        help="Print full execption output.")
-
-    # if you want different order for arguments, just change group1 with group2
-    group1 = parser.add_argument_group(_("QEMU-KVM domain"))
-    group1.add_argument("domain", default=False,
-        metavar=(_("domain_name")),
-        help=_("Choose a KVM domain name, "
-             "its the same like the configuration file name"))
-    group2 = parser.add_argument_group("Action for a domain")
-    group2.add_argument("action", choices=actions, 
-        help=_("Choose an action for the KVM guest"))
+        help="Print full python traceback.")
     
-    group3 = parser.add_argument_group("Monitor commands")
-    group3.add_argument("monitor", nargs="*", default=False,
-        metavar="option",
-        help=_("One ore more arguments can pass to the monitor."))
+    # add action as subparser
+    subparser = parser.add_subparsers(title="All commands for kvm-admin",
+        description="valid kvm-admin commands",
+        help="additional help")
+    for i in actions:
+        my_help = getattr(kvm_admin, "kvm_%s_action" % i).__doc__
+        action = subparser.add_parser(i)
+        action.add_argument(i, action="store", metavar=("domain_name"), help=my_help)
+        if i == "monitor":               
+            action.add_argument("args_monitor", nargs="*", default=[],
+                metavar=("monitor argument"),
+                help=_("One ore more arguments to pass to the qemu-kvm monitor."))
     
     args = parser.parse_args()
-
-    if args.action == "create" or args.domain in domains: 
-        kvm_admin.kvm_domain_name = args.domain
-    else:
-        parser.error(_("Available domains: %s") % domains)
-
-    kvm_admin.action = args.action
-    kvm_admin.monitor = args.monitor
+    
     kvm_admin.debug = args.debug
 
-    if not args.action == "modify" and kvm_admin.show_error() :
+    # assign the action and domain name dynamically
+    for action in actions:
+        if action in args: 
+            kvm_admin.action = action
+            kvm_admin.kvm_domain_name = str(getattr(args, action))
+            break
+
+    # assign the optional monitor arguments 
+    if "args_monitor" in args and len(args.args_monitor) > 0:
+        kvm_admin.monitor = args.args_monitor        
+    else:
+        # set default monitor to help
+        kvm_admin.monitor =["help"] 
+
+    # assign all as domain name its used for status
+    if kvm_admin.kvm_domain_name == "all" and kvm_admin.action == "status":
+        domains.append("all")
+
+    # check if the domain name has a config file and is not create
+    if not kvm_admin.kvm_domain_name in domains and not "create" == kvm_admin.action:  
+        parser.error(_("Available domains\n%s") % domains)
+
+
+    # check if some error occurs
+    if not kvm_admin.action == "modify" and kvm_admin.show_error():
         sys.exit(1)
+    
+    # run it
     if args.debug:
         kvm_admin.run()
     else:
@@ -137,6 +149,7 @@
             kvm_admin.run()
         except Exception, error_msg:
             print error_msg
+            sys.exit(1)
             
         
 if __name__ == "__main__":
@@ -144,4 +157,4 @@
         main()
     except KeyboardInterrupt:
         print _("\rUser break.")
-        sys.exit(0)
+        sys.exit(1)
--- a/kvmtools/config/kvm_parser.py	Sat Mar 31 04:53:40 2012 +0200
+++ b/kvmtools/config/kvm_parser.py	Sat Apr 07 16:38:10 2012 +0200
@@ -57,7 +57,7 @@
                                 and key not in kvm_options:
                                 print "Not a qemu-kvm command: '%s' in %s on line %s" % \
                                      (key, config_file, counter)
-                                sys.exit(1)
+                                #sys.exit(1)
                         # remove comments
                         if len(temp) == 1:
                             msg = "Missing value in %s on line %s" % \
--- a/kvmtools/header.py	Sat Mar 31 04:53:40 2012 +0200
+++ b/kvmtools/header.py	Sat Apr 07 16:38:10 2012 +0200
@@ -17,6 +17,7 @@
     """ 
 
     def __init__(self):
+        self.kvm_errors = []
         #########
         # Paths #
         #########
--- a/kvmtools/kvm/action.py	Sat Mar 31 04:53:40 2012 +0200
+++ b/kvmtools/kvm/action.py	Sat Apr 07 16:38:10 2012 +0200
@@ -18,7 +18,7 @@
 
     def __init__(self):
         Domain.__init__(self)
-        self.kvm_errors = []
+        #self.doc = False
 
     def kvm_error(self, error_message):
         """Append a error message to error list."""
@@ -34,15 +34,17 @@
         return actions
 
     def kvm_show_action(self):
-        """show the command as string"""
-        print self.command[1]
+        """Show the qemu-kvm command as string."""
+        doc = "teste a show"
+        print "default show"
+        #print self.command[1]
 
     def kvm_modify_action(self):
-        """Modify a domain configuration file."""
+        """Modify a qemu-kvm domain configuration file."""
         self.modify()
 
     def kvm_create_action(self):
-        """Create a domain configuration file."""
+        """Create a basic qemu-kvm domain configuration file."""
         if os.path.isfile(self.kvm_domain_file):
             self.modify()
         else:
@@ -52,7 +54,7 @@
     #    self.kvm_monitor_action(command_monitor)
 
     def kvm_monitor_action(self, command_monitor):
-        """Monitor to the qemu-kvm guest on commandline."""
+        """Monitor a qemu-kvm domain."""
         if not self.is_running():
             print ("Guest is not running.")
             return
@@ -62,7 +64,7 @@
         print data
 
     def kvm_boot_action(self):
-        """Boot the qemu-kvm guest."""
+        """Boot a qemu-kvm domain."""
         if self.is_running():
             print ("Guest already running.")
             return True
@@ -81,7 +83,7 @@
             return (False, error_msg)
 
     def kvm_reboot_action(self):
-        """Reboot the guest."""
+        """Reboot a qemu-kvm domain."""
         if not self.is_running():
             print ("Guest is not running.")
             return False
@@ -89,7 +91,7 @@
             print ("Could not send signal reboot to guest.")
 
     def kvm_shutdown_action(self):
-        """Shutdown the guest.
+        """Shutdown a qemu-kvm domain.
         Its work for windows and linux guests, 
         but not on linux when the Xserver is looked.
         """
@@ -128,7 +130,7 @@
             print ("Could not send signal shutdown.")
 
     def kvm_kill_action(self):
-        """Kill the guest.
+        """Kill a qemu-kvm domain.
         Dangerous option, its simply like pull the power cable out.
         """
         if not self.is_running():
@@ -145,7 +147,7 @@
             sys.exit(1)
 
     def kvm_status_action(self):
-        """Show information about the guest."""
+        """Show information about qemu-kvm domain(s)."""
         if not self.is_running():
             print ("Guest is not running.")
             return False