HowToConfigScript: Difference between revisions

From KVM
(add note about tarball being gone)
m (added categories)
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
'''NOTE: kvmctl is long gone. Ignore this page unless you already have a copy of kvmctl
= Intro =                                                                                               
= Intro =                                                                                               
I have written a utility called '''kvmctl''' to manage KVM-based VMs, along with a configuration file format, and other associated utilities.  Feel free to use it, or to expand on it.  While not strictly required by the license, I would appreciate knowing if you use it, and would appreciate being credited if you expand upon it.                                                                                           
I have written a utility called '''kvmctl''' to manage KVM-based VMs, along with a configuration file format, and other associated utilities.  Feel free to use it, or to expand on it.  While not strictly required by the license, I would appreciate knowing if you use it, and would appreciate being credited if you expand upon it.                                                                                           
Line 11: Line 8:
* all the VMs are given unique numeric identifiers between 00 and 99.  This is used for the VNC port number and the last 2 digits of the virtual MAC address.                                                     
* all the VMs are given unique numeric identifiers between 00 and 99.  This is used for the VNC port number and the last 2 digits of the virtual MAC address.                                                     
* there is a single bridge configured for all VMs to use, and all VMs will use bridged networking         
* there is a single bridge configured for all VMs to use, and all VMs will use bridged networking         
I don't proclaim to be a great shell programmer, so there are undoubtedly better ways to do a lot of things in this script.  However, this works well enough for us, covers all the things we need to do, and has been running without issues for a couple of weeks now.  I have made a bunch of changes to the script, and have released is as 2.0.2.  :)                                                                           
I don't proclaim to be a great shell programmer, so there are undoubtedly better ways to do a lot of things in this script.  However, this works well enough for us, covers all the things we need to do, and has been running without issues for a couple of weeks now.  I have made a bunch of changes to the script, and have released it as 2.0.4.  :)                                                                           


There's a simple init.d/ script included that can be used to auto-start VMs when the host system boots.  Just symlink config files into /etc/kvm/auto/ and then add the script to whichever runlevel you want.  Just be sure to set it to start after networking is up.                                                     
There's a simple init.d/ script included that can be used to auto-start VMs when the host system boots.  Just symlink config files into /etc/kvm/auto/ and then add the script to whichever runlevel you want.  Just be sure to set it to start after networking is up.                                                     
Line 17: Line 14:
= Download =
= Download =


== Version 2.0.2 ==
== Version 2.0.4 ==
Stable and working. Auto-shutdown doesn't work yet, as I haven't found a way to send a "powerdown" event to the guest OS to tell it to initiate a clean shutdown.                                                 
Stable and working. Auto-shutdown doesn't work yet, as I haven't found a way to send a "powerdown" event to the guest OS to tell it to initiate a clean shutdown.                                                 
* Download the tarball here:  [[Media:HowToConfigScript$kvmctl-2.0.2.tbz|kvmctl-2.0.2.tbz]]           
* Download the tarball here (rename to .tbz2):  [[Media:HowToConfigScript$kvmctl-2.0.4.jpg|kvmctl-2.0.4.jpg]]
* [[HowToConfigScriptSource202|Source Version 2.0.2]]


== Version 2.1.0 ==
== Version 2.1.0 ==
Line 26: Line 22:
* Download the tarball here: [[Media:kvmctl-2.1.0.tar.gz|kvmctl-2.1.0.tar.gz]]
* Download the tarball here: [[Media:kvmctl-2.1.0.tar.gz|kvmctl-2.1.0.tar.gz]]


'''NOTE: The tarball is gone, nobody has a copy, don't report this issue. This page is here strictly for people who already have kvmctl and historic purposes.
'''Note:''' The tarball for 2.1.0 is gone, nobody has a copy, don't report this issue. The above paragraph is here strictly for people who already have kvmctl 2.1.0 and for historical purposes.


= Usage =
= Usage =
Line 35: Line 31:


  # kvmctl help
  # kvmctl help
  kvmctl 2.0.2
  kvmctl 2.0.4
  Licensed under BSDL  Copyright:      2008
  Licensed under BSDL
  Copyright 2009
  kvmctl is a management and control script for KVM-based virtual machines.
  kvmctl is a management and control script for KVM-based virtual machines.
  Usage:  kvmctl start    host    - start the named VM                    
  Usage:  kvmctl start    host    - start the named VM
         kvmctl startvnc host    - start the named VM, and then connect to console via VNC
         kvmctl startvnc host    - start the named VM, and then connect to console via VNC
         kvmctl stop    host    - stop  the named VM (only use if the guest is hung)    
         kvmctl stop    host    - stop  the named VM (only use if the guest is hung)
         kvmctl restart  host    - stop and then start the named VM (only use if the guest is hung)
         kvmctl restart  host    - stop and then start the named VM (only use if the guest is hung)
         kvmctl vnc      host    - connect via VNC to the console of the named VM                
         kvmctl whichvnc host    - show which VNC display port is assigned to the named VM        
         kvmctl vnc      host    - connect via VNC to the console of the named VM
         kvmctl killvnc  host    - kills any running vncviewer processes attached to the named VM   
         kvmctl whichvnc host    - show which VNC display port is assigned to the named VM
         kvmctl edit    host    - open config file for host using $EDITOR, or create a new config file based on a template                                                                                      
         kvmctl killvnc  host    - kills any running vncviewer processes attached to the named VM
         kvmctl status          - show the names of all running VMs                                    
   
         kvmctl status  kvm    - show full details for all running kvm processes                      
         kvmctl edit    host    - open config file for host using $EDITOR, or create a new config file based on a template
         kvmctl status  host    - show full details for the named kvm process                          
         kvmctl help            - show this usage blurb                                                
         kvmctl status          - show the names of all running VMs
  ** Using stop is the same as pulling the power cord on a physical system. Use with caution.            
         kvmctl status  kvm    - show full details for all running kvm processes
         kvmctl status  host    - show full details for the named kvm process
         kvmctl help            - show this usage blurb
  ** Using stop is the same as pulling the power cord on a physical system. Use with caution.
 


To start a VM named webmail:
To start a VM named webmail:


  # kvmctl start webmail
  # kvmctl start webmail
Line 60: Line 64:


To start a VM named webmail, and then immediately attach to the console via VNC:
To start a VM named webmail, and then immediately attach to the console via VNC:


  # kvmctl startvnc webmail
  # kvmctl startvnc webmail
Line 68: Line 71:


To check the status of all running VMs (just outputs the name of the running VMs):
To check the status of all running VMs (just outputs the name of the running VMs):


  # kvmctl status
  # kvmctl status
Line 76: Line 78:


To see the process info for all the running VMs:
To see the process info for all the running VMs:


  # kvmctl status kvm
  # kvmctl status kvm
Line 84: Line 85:


To see the process info for a specific VM:
To see the process info for a specific VM:


  # kvmctl status webmail
  # kvmctl status webmail
Line 91: Line 91:


To "pull the power cord" of a running VM:
To "pull the power cord" of a running VM:


  # kvmctl stop webmail
  # kvmctl stop webmail
Line 98: Line 97:


To "powercycle" a running VM:
To "powercycle" a running VM:


  # kvmctl restart webmail
  # kvmctl restart webmail
Line 107: Line 105:


To see which VNC port has been assigned to a VM:
To see which VNC port has been assigned to a VM:


  # kvmctl whichvnc webmail
  # kvmctl whichvnc webmail
Line 113: Line 110:


To connect to the VNC port of a VM (requires vncviewer installed on the host):
To connect to the VNC port of a VM (requires vncviewer installed on the host):


  # kvmctl vnc webmail
  # kvmctl vnc webmail
Line 119: Line 115:


To create a new config file for a VM:
To create a new config file for a VM:


  # kvmctl edit newvm
  # kvmctl edit newvm
Line 126: Line 121:


To edit an existing config file:
To edit an existing config file:


  # kvmctl edit webmail
  # kvmctl edit webmail
Line 132: Line 126:


= kvmctl 2.0 config file format =
= kvmctl 2.0 config file format =
  # kvmctl Version:  2.0.0
  # kvmctl Version:  2.0.0
  # The name of the VM must be unique across all VMs running on this server
  # The name of the VM must be unique across all VMs running on this server
  host="webmail"                                                          
  # This is not actually used anywhere, instead kvmctl uses the filename without
  # An ID number for the VM.                                              
# the .kvm as the host name.
# host="hostname"
  # An ID number for the VM.  
  # This is used to generate the MAC address of the virtual NIC, the tap device in the host, and
  # This is used to generate the MAC address of the virtual NIC, the tap device in the host, and
  # the VNC port for the VM's console.                                                        
  # the VNC port for the VM's console.
  id="12"                                                                                      
  id="##"
  # How much RAM to associate with the VM.                                                    
  # This is the max amount of RAM that it will use.                                            
  # How much RAM to associate with the VM.
  mem="2048"                                                                                  
  # This is the max amount of RAM that it will use.
  # Whether to enable ACPI support in the virtual BIOS                                        
  mem="1024"
  # Default is to enable ACPI                                                                  
  # noacpi cannot be set if cpus > 1.                                                          
  # Whether to enable ACPI support in the virtual BIOS
  noacpi=""                                                                                    
  # Default is to enable ACPI
  # The number of virtual CPUs to assign to the VM.                                            
  # noacpi cannot be set if cpus > 1.
  # Stable values are 1-4.                                                                    
  noacpi=""
  # cpus must be set to 1 if noacpi is set.                                                    
  cpus="2"                                                                                    
  # The number of virtual CPUs to assign to the VM.
  # Which mouse device to use                                                                  
  # Stable values are 1-4.
  # Values:  mouse, tablet                                                                    
  # cpus must be set to 1 if noacpi is set.
  # Default: tablet                                                                            
  cpus="1"
  mouse="tablet"                                                                              
  # The network chipset to use in the VM.                                                      
  # Which mouse device to use
  # Values:  rtl1389, e1000                                                                    
  # Values:  mouse, tablet
  # Default: rtl8139                                                                          
  # Default: tablet
  nic="e1000"                                                                                  
  mouse="tablet"
  # Which virtual block device to boot from                                                    
  # Values:  a=floppy0, b=floppy1, c=disk0, d=disk1                                            
  # The network chipset to use in the VM.
  # Default: c                                                                                
  # Values:  rtl1389, e1000
  boot="c"                                                                                    
  # Default: rtl8139
  # If the VM is set to boot from "d" and "d" is a CD-ROM, an extra '-no-reboot'              
  nic="rtl8139"
  # option is added to the kvm commandline.  This will cause the VM to treat a                
  # "reboot" command as if it were a "shutdown" command.                                      
  # Which virtual block device to boot from
  # Values  for disktype: ide, scsi, virtio                                                    
  # Values:  a=floppy0, b=floppy1, c=disk0, d=disk1
  # Default: c
  boot="c"
  # If the VM is set to boot from "d" and "d" is a CD-ROM, an extra '-no-reboot'
  # option is added to the kvm commandline.  This will cause the VM to treat a
  # "reboot" command as if it were a "shutdown" command.
  # Values  for disktype: ide, scsi, virtio
  # Default for disktype: ide
  # Default for disktype: ide
  # If the value for disktyp0 is scsi or virtio, an extra ',boot=on' option will
  # If the value for disktyp0 is scsi or virtio, an extra ',boot=on' option will
  # be added to the kvm commandline.  This is needed in order to boot from SCSI
  # be added to the kvm commandline.  This is needed in order to boot from SCSI
  # and paravirtualised block devices.
  # and paravirtualised block devices.
  # Values  for media:    disk, cdrom
  # Values  for media:    disk, cdrom
  # Default for disktype: disk
  # Default for disktype: disk
  # Values  for disk:    a path to either a disk image file, or an LVM logical volume
  # Values  for disk:    a path to either a disk image file, or an LVM logical v volume
  # Default for disk:    /dev/mapper/vol0-${host}
  # Default for disk:    /dev/mapper/vol0-${host}
  # The first virtual block device
  # The first virtual block device
  # For IDE devices, this is primary master.
  # For IDE devices, this is primary master.
  disktype0="ide"
  disktype0="ide"
  media0="disk"
  media0="disk"
  disk0="/dev/mapper/vol0-webmail"
  disk0="/path/to/diskimage"
  # The second virtual block device
  # The second virtual block device
  # For IDE devices, this is primary slave.
  # For IDE devices, this is primary slave.
Line 185: Line 195:
  media1=""
  media1=""
  disk1=""
  disk1=""
  # The third virtual block device
  # The third virtual block device
  # For IDE devices, this is secondary master
  # For IDE devices, this is secondary master
Line 190: Line 201:
  disktype2="ide"
  disktype2="ide"
  media2="cdrom"
  media2="cdrom"
  disk2="/home/iso/debian-40r3-amd64-netinst.iso"
  disk2="/path/to/osinstall.iso"
  # The fourth virtual block device
  # The fourth virtual block device
  # For IDE devices, this is secondary slave
  # For IDE devices, this is secondary slave
Line 196: Line 208:
  media3=""
  media3=""
  disk3=""
  disk3=""
[[Category:Docs]][[Category:Management]][[Category:Historical]]

Latest revision as of 10:21, 31 May 2015

Intro

I have written a utility called kvmctl to manage KVM-based VMs, along with a configuration file format, and other associated utilities. Feel free to use it, or to expand on it. While not strictly required by the license, I would appreciate knowing if you use it, and would appreciate being credited if you expand upon it.

A couple of assumptions are made for this work:

  • all the VMs have unique host names.
  • all the VMs have config files in /etc/kvm that are named <host>.kvm. These are shell script fragments that initialise variabless related to the VM.
  • all the VMs are given unique numeric identifiers between 00 and 99. This is used for the VNC port number and the last 2 digits of the virtual MAC address.
  • there is a single bridge configured for all VMs to use, and all VMs will use bridged networking

I don't proclaim to be a great shell programmer, so there are undoubtedly better ways to do a lot of things in this script. However, this works well enough for us, covers all the things we need to do, and has been running without issues for a couple of weeks now. I have made a bunch of changes to the script, and have released it as 2.0.4.  :)

There's a simple init.d/ script included that can be used to auto-start VMs when the host system boots. Just symlink config files into /etc/kvm/auto/ and then add the script to whichever runlevel you want. Just be sure to set it to start after networking is up.

Download

Version 2.0.4

Stable and working. Auto-shutdown doesn't work yet, as I haven't found a way to send a "powerdown" event to the guest OS to tell it to initiate a clean shutdown.

Version 2.1.0

I've added a possibility to start a monitor port as telnet server and added a shutdown. Since debian has removed bash tcp support i need netcat (nc) to send a power-button-press to the monitor of virtual machine. So if you like to test the shutdown, start the machine with a monitor and install "nc". This Version includes some other changes and is not roughly tested.

Note: The tarball for 2.1.0 is gone, nobody has a copy, don't report this issue. The above paragraph is here strictly for people who already have kvmctl 2.1.0 and for historical purposes.

Usage

The script can be run as a normal user. It uses sudo internally for the start/stop commands (all the rest are run as the normal user). Currently, all kvm processes are run as root, as this was developed on Debian Lenny which (for whatever reason) decided to include kernel capabilities which prevents non-root users from accessing tun devices.

To see a blurb that describe all the options:


# kvmctl help
kvmctl 2.0.4
Licensed under BSDL
Copyright 2009

kvmctl is a management and control script for KVM-based virtual machines.

Usage:  kvmctl start    host    - start the named VM
        kvmctl startvnc host    - start the named VM, and then connect to console via VNC
        kvmctl stop     host    - stop  the named VM (only use if the guest is hung)
        kvmctl restart  host    - stop and then start the named VM (only use if the guest is hung)

        kvmctl vnc      host    - connect via VNC to the console of the named VM
        kvmctl whichvnc host    - show which VNC display port is assigned to the named VM
        kvmctl killvnc  host    - kills any running vncviewer processes attached to the named VM

        kvmctl edit     host    - open config file for host using $EDITOR, or create a new config file based on a template

        kvmctl status           - show the names of all running VMs
        kvmctl status   kvm     - show full details for all running kvm processes
        kvmctl status   host    - show full details for the named kvm process

        kvmctl help             - show this usage blurb

** Using stop is the same as pulling the power cord on a physical system. Use with caution.


To start a VM named webmail:

# kvmctl start webmail
Starting webmail.     
The VNC port for webmail is :05

To start a VM named webmail, and then immediately attach to the console via VNC:

# kvmctl startvnc webmail
Starting webmail.        
The VNC port for webmail is :05
<vncviewer is started>         

To check the status of all running VMs (just outputs the name of the running VMs):

# kvmctl status
The following VMs are running:
fcsync                        
webmail                       

To see the process info for all the running VMs:

# kvmctl status kvm
The following VMs are running:
3792 /usr/bin/kvm -name fcsync -daemonize -localtime -usb -usbdevice tablet -smp 1 -m 1048 -vnc :02 -pidfile /var/run/kvm/fcsync.pid -net nic,macaddr=00:16:3e:00:00:02,model=rtl8139 -net tap,ifname=tap02 -boot c -drive index=0,media=disk,if=ide,file=/dev/mapper/vol0-fcsync                                         
5123 /usr/bin/kvm -name webmail -daemonize -localtime -usb -usbdevice tablet -smp 2 -m 2048 -vnc :05 -pidfile /var/run/kvm/webmail.pid -net nic,macaddr=00:16:3e:00:00:05,model=e1000 -net tap,ifname=tap05 -boot c -drive index=1,media=disk,if=scsi,file=/dev/mapper/vol0-webmail--storage -drive index=0,media=disk,if=ide,file=/dev/mapper/vol0-webmail                                                                        

To see the process info for a specific VM:

# kvmctl status webmail
VM for host webmail is running with:
5123 /usr/bin/kvm -name webmail -daemonize -localtime -usb -usbdevice tablet -smp 2 -m 2048 -vnc :05 -pidfile /var/run/kvm/webmail.pid -net nic,macaddr=00:16:3e:00:00:05,model=e1000 -net tap,ifname=tap05 -boot c -drive index=1,media=disk,if=scsi,file=/dev/mapper/vol0-webmail--storage -drive index=0,media=disk,if=ide,file=/dev/mapper/vol0-webmail                                                                        

To "pull the power cord" of a running VM:

# kvmctl stop webmail
Attempting to stop VM for webmail
VM for webmail has stopped       

To "powercycle" a running VM:

# kvmctl restart webmail
Attempting to stop VM for webmail
VM for webmail has stopped       
Starting webmail.                
The VNC port for webmail is :05  

To see which VNC port has been assigned to a VM:

# kvmctl whichvnc webmail
The VNC port for webmail is :05

To connect to the VNC port of a VM (requires vncviewer installed on the host):

# kvmctl vnc webmail
<vncviewer is started>

To create a new config file for a VM:

# kvmctl edit newvm
/etc/kvm/test.kvm does not exist.  Would you like to create one from the template? (y/n)
<if yes, $EDITOR is opened with the template loaded>                                    

To edit an existing config file:

# kvmctl edit webmail
<$EDITOR is opened with /etc/kvm/webmail.kvm loaded.>

kvmctl 2.0 config file format

# kvmctl Version:  2.0.0

# The name of the VM must be unique across all VMs running on this server
# This is not actually used anywhere, instead kvmctl uses the filename without
# the .kvm as the host name.
# host="hostname"

# An ID number for the VM. 
# This is used to generate the MAC address of the virtual NIC, the tap device in the host, and
# the VNC port for the VM's console.
id="##"

# How much RAM to associate with the VM.
# This is the max amount of RAM that it will use.
mem="1024"

# Whether to enable ACPI support in the virtual BIOS
# Default is to enable ACPI
# noacpi cannot be set if cpus > 1.
noacpi=""

# The number of virtual CPUs to assign to the VM.
# Stable values are 1-4.
# cpus must be set to 1 if noacpi is set.
cpus="1"

# Which mouse device to use
# Values:  mouse, tablet
# Default: tablet
mouse="tablet"

# The network chipset to use in the VM.
# Values:  rtl1389, e1000
# Default: rtl8139
nic="rtl8139"

# Which virtual block device to boot from
# Values:  a=floppy0, b=floppy1, c=disk0, d=disk1
# Default: c
boot="c"

# If the VM is set to boot from "d" and "d" is a CD-ROM, an extra '-no-reboot'
# option is added to the kvm commandline.  This will cause the VM to treat a
# "reboot" command as if it were a "shutdown" command.

# Values  for disktype: ide, scsi, virtio
# Default for disktype: ide

# If the value for disktyp0 is scsi or virtio, an extra ',boot=on' option will
# be added to the kvm commandline.  This is needed in order to boot from SCSI
# and paravirtualised block devices.

# Values  for media:    disk, cdrom
# Default for disktype: disk

# Values  for disk:     a path to either a disk image file, or an LVM logical v volume
# Default for disk:     /dev/mapper/vol0-${host}

# The first virtual block device
# For IDE devices, this is primary master.
disktype0="ide"
media0="disk"
disk0="/path/to/diskimage"

# The second virtual block device
# For IDE devices, this is primary slave.
disktype1=""
media1=""
disk1=""

# The third virtual block device
# For IDE devices, this is secondary master
# USE THIS FOR CD-ROMS OR PERFORMANCE WILL SUFFER GREATLY!!
disktype2="ide"
media2="cdrom"
disk2="/path/to/osinstall.iso"

# The fourth virtual block device
# For IDE devices, this is secondary slave
disktype3=""
media3=""
disk3=""