Xen » virtcfg & virtadm: making xVM guest administration easy
en

virtcfg & virtadm: making xVM guest administration easy

virtcfg & virtadm: making xVM guest administration easy

Introduction

virtcfg and virtadm were written to make configuration, installation and maintenance of xVM guests on an OpenSolaris dom0 much easier.

Using syntax similar to zonecfg(1M)/zoneadm(1M) the tools should be very familiar to people already used to managing zones on OpenSolaris.  The tools, written in Python, make use of libvirt on the back-end to communicate with the hypervisor.  Whilst xVM dom0 on OpenSolaris is the only available back-end now, the design of this tool-set should allow it to act as a common front-end for other virtualization solutions: xVM, LDOMs, VirtualBox, perhaps even Zones at some point.

There are no plans yet to integrate these utilities into OpenSolaris - the tools are provided here purely for interested developers to download and experiment with and we would welcome your feedback on the xen-discuss alias.

In this document, we'll walk through a quick example, then show the usage for both tools.

Sources and compiling:

 $ hg clone ssh://anon@hg.opensolaris.org//hg/xen-gate/virtcfg-gate
 $ cd virtcfg-gate
 $ make pkg
 .
 .
 $ pfexec pkgadd -d packages SUNWvirt

To install SUNWvirt, the following packages must exist on the system:
(for the most part, these are same things you need to run virt-install)

  • OpenSolaris xVM hypervisor support nv_129 or later (SUNWxvm)
  • SUNWxvmdom
  • SUNWlibvirt
  • SUNWurlgrabber
  • SUNWvdisk
  • SUNWvirtinst
  • SUNWunzip
  • SUNWPython26
  • SUNWp7zip
  • SUNWpython-lxml
  • SUNWvncviewer 

virtcfg

This tool provides a simple interactive or scriptable CLI to configure guests.

It is based around the concepts of resources and properties.  We can navigate around a directory-tree of these resources, adding new resources and setting properties on those resources as needed.

Help is provided throughout the CLI using the 'help' command, and extended prompting can be turned on using the 'prompt' command.

To script virtcfg, users can simply echo or cat commands through a pipe to virtcfg's stdin or just run virtcfg commands from the command line, eg. 'virtcfg list -r myguest'

Out of the box, several default guest templates are provided.  We can create new templates from any existing guest or resource (see 'help commit').  Templates that create an entire guest allows the user to run 'virtcfg -t myguest_template newguest' from the command line, whereas templates of individual resources allow us to add that resource with a template, eg. 'add -t mydisk disk'

We use the 'context' command to switch virtcfg between several different guest contexts, allowing it to configure the permanent state of the guest, the guest's runtime state, or the state of the guest the next time it is booted.

virtadm

Taking configurations created by virtcfg, virtadm is responsible for installing and managing guest state.

Examples

virtcfg example

Here is a simple example showing us creating an OpenSolaris guest:

-bash-4.0# virtcfg templates guest
NAME                TYPE          LOCATION
centos-5.4          guest         -
debian-lenny        guest         -
fedora-11           guest         -
linux-hvm           guest         -
linux-pv            guest         -
opensolaris         guest         -
solaris10           guest         -
ubuntu              guest         -
windows-xp          guest         -
-bash-4.0# virtcfg -t opensolaris myguest
creating new guest guest from template opensolaris

.
. [ omitting help messages]

(myguest)/:> ls
id/
boot/
params/
devices/
install/
cpu_capped: 1
memory: 1024M
(myguest)/:> cd devices/network/datalink
(myguest)/devices/network/datalink:> ls
cappedbandwidth: [unset]
mac: [unset]
name: auto
over: auto
type: vnic
vlan: [unset]
(myguest)/devices/network/datalink:> set mac=auto
(myguest)/devices/network/datalink:> cd /
(myguest)/:> cd install
(myguest)/install:> ls
configuration: [unset]
source: file:///path/to/opensolaris-dvd.iso
status: configured
type: cd
(myguest)/install:> set source=/rpool/guests/osol-dev-129-x86.iso
(myguest)/install:> cd /devices
(myguest)/devices:> templates disk
NAME                TYPE          LOCATION
iscsi               disk          /devices
iso                 disk          /devices
path                disk          /devices
zvol                disk          /devices
(myguest)/devices:> add -t zvol disk
(myguest)/devices/disk:> set volume/capacity=16g
(myguest)/devices/disk:> set volume/name=rpool/guests/myguestdsk
(myguest)/devices/disk:> cd /
(myguest)/:> set memory=2048m
(myguest)/:> set cpu_capped=2
(myguest)/:> commit
virtcfg: written myguest
(myguest)/:> exit

virtadm example

# virtadm list
NAME                TYPE BRAND  STATE  
myguest             xen  pv     halted 
osol                xen  pv     halted 
zone-10-5-236-226   xen  pv     running
newguest            xen  pv     running
# virtadm install myguest
virtadm: creating ZFS volume rpool/guests/myguestdsk ... done
virtadm: waiting for myguest to start ..........

virtadm: waiting for install completion
Connected to domain 15
Escape character is '^]'
v3.4.2-xvm-debug chgset 'Sun Dec 06 22:26:11 2009 -0800 19673:56d9e54df9d2'
SunOS Release 5.11 Version snv_129 64-bit
Copyright 1983-2009 Sun Microsystems, Inc.  All rights reserved.
Use is subject to license terms.
Hostname: opensolaris
Remounting root read/write
Probing for device nodes ...
Preparing live image for use


[ install guest as usual ]

Usage

virtcfg usage

$ virtcfg --help
Usage:

virtcfg - Configure guests or create/modify guest templates

virtcfg [-c <context>] [-t template] name

-c      Specify the context for editing the guest configuration
-t      Template to use when creating a guest

virtcfg starts and provides an interactive shell which accepts commands
to be run on the named guest configuration, or template.  If a guest
with the given name does not yet exist, one is created based upon the
given template, or the default guest template.

Help is provided using the command "help".

The context can be provided, allowing the editing of the guest
just for that particular context. Supported contexts are:
next, permanent, runtime

When provided with standard input, commands are read from that
input and applied to the given guest or template.

EXAMPLES:
    $ virtcfg myguest
    $ virtcfg -c next myguest
    $ echo 'cd devices
    > add -t iscsi disk
    > commit' | virtcfg myguest    
    $ virtcfg mytemplate
    $ virtcfg help add

Usage:
 add [ -t tmpl ] <resource>        Add a resource
 clear <property> ...              Clear one or more properties
 clone <new guest>                 Clone a guest
 commit [-f] [-t] [-n] [name]      Save configuration or template
 context [context]                 Switch context
 delete <name>                     Delete a template or guest configuration
 exit                              Exit virtcfg
 get | info [-p] <prop> ...        Get one or more property values
 help [object] | [cmd]             Show help for a resource, property or command
 history [-c]                      Print command history
 list | ls [-r] [-l|-p] [path]..   List resources
 prompt [on|off]                   Toggle or set the extended CLI prompting
 remove | rm <expr> ...            Remove one or more resources or properties
 select | cd [expr]                Navigate around the tree
 set <prop>=<value>                Set a property value
 templates [-pH] [-o field] [name] List templates

virtadm usage


$ virtadm --help

virtadm [-d dbg] [-q?] subcmd ...
  -q, --quiet           suppress verbose output
  -d DEBUG, --debug=DEBUG
                        set debug options
  -?, --help            show usage message

virtadm boot [-CcdW] [-t timeout] guestname
  -C, --no-console      don't connect to the guest console
  -t TIMEOUT, --timeout=TIMEOUT
                        timeout in seconds
  -W, --no-wait         don't wait
  -c, --text            connect to the guest's text console
  -d, --display         connect to the guest's display

virtadm halt [-fW] [-t timeout] guestname
  -t TIMEOUT, --timeout=TIMEOUT
                        timeout in seconds
  -W, --no-wait         don't wait
  -f, --force           destroy guest

virtadm reboot [-CcdW] [-t timeout] guestname
  -C, --no-console      don't connect to the guest console
  -c, --console         connect to the guest's text console
  -d, --display         connect to the guest's display
  -t TIMEOUT, --timeout=TIMEOUT
                        timeout in seconds
  -W, --no-wait         don't wait

virtadm console [-cd] guestname
  -c, --text     connect to the guest's text console
  -d, --display  connect to the guest's display

virtadm refresh guestname

virtadm list [-o field,... -p] [guestname[,...]]
  -H, --no-header       don't output header
  -o FIELDS, --output=FIELDS
                        output given fields
  -p, --parseable       output machine-readable format

virtadm install [-CcdtW] guestname
  -C, --no-console      don't connect to the guest console
  -c, --text            connect to the guest's text console
  -d, --display         connect to the guest's display
  -t TIMEOUT, --timeout=TIMEOUT
                        timeout in seconds
  -W, --no-wait         don't wait

virtadm import [-f] source [dest]
  -f, --force  import over existing guest

virtadm export -f format guestname destination
  -f FORMAT, --format=FORMAT
                        output format

virtadm migrate [-nw] guestname destination
  -n, --dry-run  perform a dry-run test
  -w, --warm     warm migrate

virtadm suspend guestname [destination]

virtadm resume [-pr] guestname [source]
  -p, --preserve  preserve image file
  -r, --remove    remove image file

virtadm dump guestname [outpath]

virtadm group [list|add|remove] [group] [args...]
  -p, --parseable       output machine-readable format
  -h HOST, --host=HOST  host name
  -d DOMAIN, --domain=DOMAIN
                        domain name

virtadm history [-c] [-Hp] [-o field,...]
  -c, --clear           clear history
  -H, --no-header       don't output header
  -o FIELDS, --output=FIELDS
                        output given fields
  -p, --parseable       output machine-readable format
Tags:
Created by Tim Foster on 2010/01/06 09:13
Last modified by Tim Foster on 2010/01/06 09:52
XWiki Enterprise 2.7.1.34853 - Documentation