understanding the XEN xm list command

When maintaining a XEN Oracle VM server one of the commands you will most likely be using a lot is the list command. list will give you a overview of which virtual machine is where, which virtual machine is running, which virtual machine is down and such things. Understanding the list command is vital to understanding your server landscape and monitor things.

We will be working in this post on the XEN xm shell as described in a previous post. XEN states the following about the list command: "List information about all/some domains".

xm> help list
Usage: xm list [options] [Domain, ...]

List information about all/some domains.
-l, --long Output all VM details in SXP
--label Include security labels
--state= Select only VMs with the specified state

xm>

the help list command is already showing you some of the options you will have at the list command. issuing the list command 'stand alone' is providing a output like the one below:

xm> list
Name ID Mem VCPUs State Time(s)
48_VM1 3 1024 1 -b---- 27356.4
Domain-0 0 581 2 r----- 395481.0
xm>

ID is showing you the 'internal' XEN domain ID or 'Virtual machine ID'. this ID is used at other commands to issue commands to take actions on a domain. For example if you want to shutdown a domain you issue the command shutdown -w (domain ID).

Mem is showing you the memory assigned to the domain in megabytes. In the example above you can see that domain 48_VM1 has 1024MB allocated and Domain-0 has 581MB assigned. This is not saying anything about how much of this memory is used within the domain by the virtual machine.

Time(s) is showing the time the domain is running.

State; the State field lists 6 states for a Xen Domain, and which ones the current Domain is in.
r - running
The domain is currently running on a CPU
b - blocked
The domain is blocked, and not running or runnable. This can be caused because the domain is waiting on IO (a traditional wait state) or has gone to sleep because there was nothing else for it to do.
p - paused
The domain has been paused, usually occurring through the administrator running xm pause. When in a paused state the domain will still consume allocated resources like memory, but will not be eligible for scheduling by the Xen hypervisor.
s - shutdown
The guest has requested to be shutdown, rebooted or suspended, and the domain is in the process of being destroyed in response.
c - crashed
The domain has crashed, which is always a violent ending. Usually this state can only occur if the domain has been configured not to restart on crash. See xmdomain.cfg for more info.
d - dying
The domain is in process of dying, but hasn't completely shutdown or crashed.

By adding --label to the list command you will get the security label added at the end of the records. Below you can see a example where I did not set security labels to the domains. For more information about adding security labels to XEN domains take a look at linuxtopia.org

xm> list --label
Name ID Mem VCPUs State Time(s) Label
48_VM1 3 1024 1 -b---- 27372.1 INACTIVE
Domain-0 0 581 2 r----- 395658.0 INACTIVE
xm>

By adding a -l or --long to the list command you will get a lot more information about the domains running on your XEN server. The information is represented in a S-expression format. Xen states the following about the list -l option: "If --long is specified, the output for xm list is not the table view shown above, but instead is an S-Expression representing all information known about all domains asked for. This is mostly only useful for external programs to parse the data.". I tend to disagree with XEN on the "This is mostly only useful for external programs to parse the data" section. You can quickly see a lot of information you might need about a domain in the S-Expression representation.

Wikipedia states the following about S-Expressions:
"The term S-expression or sexp (where S stands for symbolic) refers to a convention for representing semi-structured data in human-readable textual form. S-expressions are probably best known for their use in the Lisp family of programming languages. Other uses of S-expressions are in Lisp-derived languages such as DSSSL, and as mark-up in communications protocols like IMAP and John McCarthy's CBCL. The details of the syntax and supported data types vary in the different languages, but the most common feature among these languages is the use of S-expressions as parenthesized prefix notation (sometimes known as Cambridge Polish notation).

S-expressions are used for both code and data in Lisp (see McCarthy Recursive Functions of Symbolic Expressions [1]). S-expressions were originally intended only for data to be manipulated by M-expressions, but the first implementation of Lisp was an interpreter of S-expression encodings of M-expressions, and Lisp programmers soon became accustomed to using S-expressions for both code and data.".

The S-expression output of XEN on a domain or on all domains will be explained in a future post. This is to much to discuss right now.