view docs/src/user/domain_mgmt.tex @ 7176:0e1838de9db8

Move XendDomainInfo.{create,recreate,parseConfig} to the top level of the
domain. This allows us to refer to them using an import statement, rather than
a from .. import. This is a step towards getting rid of the xroot hack. All
other references to XendDomainInfo methods need to be doubly qualified (once
for the module, once for the class).

Remove XendDomainDict, replacing it with a simple dictionary, folding the
get_by_name method into XendDomain.

Replace XendDomain.refresh_lock with a domains_lock which goes around any
reference to XendDomain.domains or anything that will create or destroy a
domain. This serialises most accesses through XendDomain, ensuring that we will
not return stale state when racing against the watches fired in separate
threads. This should have fixed bugs #270 and #234.

Added a number of domain_get_xyz methods. Those named xyz_nr are to allow
components internal to XendDomain (XendDomainInfo, XendCheckpoint) to call back
into XendDomain without triggering further calls to XendDomain.refresh. The
other methods simply make it clear which fallback behaviour is expected.

Replace XendDomainInfo.domain_exists with XendDomainInfo.domain_by_name; the
internals of this method needed to change to match those changes above, and it
has been a misnomer for some time.

Signed-off-by: Ewan Mellor <ewan@xensource.com>
author emellor@ewan
date Tue Oct 04 02:21:28 2005 +0100 (2005-10-04)
parents 06d84bf87159
children 07b5b3e2ff45
line source
1 \chapter{Domain Management Tools}
3 The previous chapter described a simple example of how to configure
4 and start a domain. This chapter summarises the tools available to
5 manage running domains.
8 \section{Command-line Management}
10 Command line management tasks are also performed using the \path{xm}
11 tool. For online help for the commands available, type:
12 \begin{quote}
13 \verb_# xm help_
14 \end{quote}
16 You can also type \path{xm help $<$command$>$} for more information on
17 a given command.
19 \subsection{Basic Management Commands}
21 The most important \path{xm} commands are:
22 \begin{quote}
23 \verb_# xm list_: Lists all domains running.\\
24 \verb_# xm consoles_: Gives information about the domain consoles.\\
25 \verb_# xm console_: Opens a console to a domain (e.g.\
26 \verb_# xm console myVM_)
27 \end{quote}
29 \subsection{\tt xm list}
31 The output of \path{xm list} is in rows of the following format:
32 \begin{center} {\tt name domid memory cpu state cputime console}
33 \end{center}
35 \begin{quote}
36 \begin{description}
37 \item[name] The descriptive name of the virtual machine.
38 \item[domid] The number of the domain ID this virtual machine is
39 running in.
40 \item[memory] Memory size in megabytes.
41 \item[cpu] The CPU this domain is running on.
42 \item[state] Domain state consists of 5 fields:
43 \begin{description}
44 \item[r] running
45 \item[b] blocked
46 \item[p] paused
47 \item[s] shutdown
48 \item[c] crashed
49 \end{description}
50 \item[cputime] How much CPU time (in seconds) the domain has used so
51 far.
52 \item[console] TCP port accepting connections to the domain's
53 console.
54 \end{description}
55 \end{quote}
57 The \path{xm list} command also supports a long output format when the
58 \path{-l} switch is used. This outputs the fulls details of the
59 running domains in \xend's SXP configuration format.
61 For example, suppose the system is running the ttylinux domain as
62 described earlier. The list command should produce output somewhat
63 like the following:
64 \begin{verbatim}
65 # xm list
66 Name Id Mem(MB) CPU State Time(s) Console
67 Domain-0 0 251 0 r---- 172.2
68 ttylinux 5 63 0 -b--- 3.0 9605
69 \end{verbatim}
71 Here we can see the details for the ttylinux domain, as well as for
72 domain~0 (which, of course, is always running). Note that the console
73 port for the ttylinux domain is 9605. This can be connected to by TCP
74 using a terminal program (e.g. \path{telnet} or, better,
75 \path{xencons}). The simplest way to connect is to use the
76 \path{xm~console} command, specifying the domain name or ID. To
77 connect to the console of the ttylinux domain, we could use any of the
78 following:
79 \begin{verbatim}
80 # xm console ttylinux
81 # xm console 5
82 # xencons localhost 9605
83 \end{verbatim}
85 \section{Domain Save and Restore}
87 The administrator of a Xen system may suspend a virtual machine's
88 current state into a disk file in domain~0, allowing it to be resumed
89 at a later time.
91 The ttylinux domain described earlier can be suspended to disk using
92 the command:
93 \begin{verbatim}
94 # xm save ttylinux ttylinux.xen
95 \end{verbatim}
97 This will stop the domain named `ttylinux' and save its current state
98 into a file called \path{ttylinux.xen}.
100 To resume execution of this domain, use the \path{xm restore} command:
101 \begin{verbatim}
102 # xm restore ttylinux.xen
103 \end{verbatim}
105 This will restore the state of the domain and restart it. The domain
106 will carry on as before and the console may be reconnected using the
107 \path{xm console} command, as above.
109 \section{Live Migration}
111 Live migration is used to transfer a domain between physical hosts
112 whilst that domain continues to perform its usual activities --- from
113 the user's perspective, the migration should be imperceptible.
115 To perform a live migration, both hosts must be running Xen / \xend\
116 and the destination host must have sufficient resources (e.g.\ memory
117 capacity) to accommodate the domain after the move. Furthermore we
118 currently require both source and destination machines to be on the
119 same L2 subnet.
121 Currently, there is no support for providing automatic remote access
122 to filesystems stored on local disk when a domain is migrated.
123 Administrators should choose an appropriate storage solution (i.e.\
124 SAN, NAS, etc.) to ensure that domain filesystems are also available
125 on their destination node. GNBD is a good method for exporting a
126 volume from one machine to another. iSCSI can do a similar job, but is
127 more complex to set up.
129 When a domain migrates, it's MAC and IP address move with it, thus it
130 is only possible to migrate VMs within the same layer-2 network and IP
131 subnet. If the destination node is on a different subnet, the
132 administrator would need to manually configure a suitable etherip or
133 IP tunnel in the domain~0 of the remote node.
135 A domain may be migrated using the \path{xm migrate} command. To live
136 migrate a domain to another machine, we would use the command:
138 \begin{verbatim}
139 # xm migrate --live mydomain destination.ournetwork.com
140 \end{verbatim}
142 Without the \path{--live} flag, \xend\ simply stops the domain and
143 copies the memory image over to the new node and restarts it. Since
144 domains can have large allocations this can be quite time consuming,
145 even on a Gigabit network. With the \path{--live} flag \xend\ attempts
146 to keep the domain running while the migration is in progress,
147 resulting in typical `downtimes' of just 60--300ms.
149 For now it will be necessary to reconnect to the domain's console on
150 the new machine using the \path{xm console} command. If a migrated
151 domain has any open network connections then they will be preserved,
152 so SSH connections do not have this limitation.
155 \section{Managing Domain Memory}
157 XenLinux domains have the ability to relinquish / reclaim machine
158 memory at the request of the administrator or the user of the domain.
160 \subsection{Setting memory footprints from dom0}
162 The machine administrator can request that a domain alter its memory
163 footprint using the \path{xm set-mem} command. For instance, we can
164 request that our example ttylinux domain reduce its memory footprint
165 to 32 megabytes.
167 \begin{verbatim}
168 # xm set-mem ttylinux 32
169 \end{verbatim}
171 We can now see the result of this in the output of \path{xm list}:
173 \begin{verbatim}
174 # xm list
175 Name Id Mem(MB) CPU State Time(s) Console
176 Domain-0 0 251 0 r---- 172.2
177 ttylinux 5 31 0 -b--- 4.3 9605
178 \end{verbatim}
180 The domain has responded to the request by returning memory to Xen. We
181 can restore the domain to its original size using the command line:
183 \begin{verbatim}
184 # xm set-mem ttylinux 64
185 \end{verbatim}
187 \subsection{Setting memory footprints from within a domain}
189 The virtual file \path{/proc/xen/balloon} allows the owner of a domain
190 to adjust their own memory footprint. Reading the file (e.g.\
191 \path{cat /proc/xen/balloon}) prints out the current memory footprint
192 of the domain. Writing the file (e.g.\ \path{echo new\_target >
193 /proc/xen/balloon}) requests that the kernel adjust the domain's
194 memory footprint to a new value.
196 \subsection{Setting memory limits}
198 Xen associates a memory size limit with each domain. By default, this
199 is the amount of memory the domain is originally started with,
200 preventing the domain from ever growing beyond this size. To permit a
201 domain to grow beyond its original allocation or to prevent a domain
202 you've shrunk from reclaiming the memory it relinquished, use the
203 \path{xm maxmem} command.