[% topdir = "../.." -%]
[% PROCESS globals -%]
[% WRAPPER page
   title = "Starting and stopping virtual machines with virt-manager"
   h1 = "Starting and stopping virtual machines with virt-manager"
   section = "learning"
%]

<p>
In principle, <q>lifecycle management</q> (which is a fancy way of
saying <q>starting and stopping virtual machines</q>) is quite easy.
</p>

[% WRAPPER h2 h2="Starting the virtual machine" anchor="start" %]

<p>
To start a virtual machine running, select it from the list and either
press the <q>play</q> button or right click and select <q>Run</q>:
</p>

<p>
<img src="run.png" width="312" height="315"
  longdesc="Screenshot showing the right button popup menu in virt-manager" />
</p>

<p>
When the virtual machine is running, two things will change.  You
will get a small graph showing the CPU usage in the main virt-manager
window.  And if you double click on the virtual machine, virt-manager
will open another window showing you the console:
</p>

<p>
<img src="debian.png" width="946" height="677"
  longdesc="Screenshot showing virtual machine running" />
</p>

[% END %]

[% WRAPPER h2 h2="Stopping the virtual machine" anchor="stop" %]

<p>
Stopping the virtual machine is a little more complex and requires
some understanding of how real PC hardware works.
</p>

<h3>Force off</h3>

<p>
On a real PC you can just pull out the power cord (and battery
if it's a laptop).  This abruptly shuts the machine down, but
it's not usually a good thing to do since the operating system
gets no time to gracefully shut down applications and synchronize
the disk.
</p>

<p>
Nevertheless virt-manager lets you do this: From the <q>switch</q>
menu select <q>Force Off</q>:
</p>

<p>
<img src="force-off.png" width="310" height="193"
  longdesc="Screenshot showing force-off option in virt-manager" />
</p>

<h3>ACPI</h3>

<p>
The other two options on this menu are <q>Reboot</q> and
<q>Shut Down</q>.  However you cannot reboot or shut down
a machine (real or virtual) without cooperation from the
operating system.  On a real PC the power switch just sends
a signal to the operating system, and the operating system
has to be listening out for the signal and has to react
by doing the right thing.  This signal mechanism
is known as
<a href="http://en.wikipedia.org/wiki/ACPI">ACPI</a>.
The same mechanism is used to <q>wire</q> the virtual power
switch to the virtual machine.
</p>

<p>
This is why pressing the virtual power button may
open a dialog inside the VM like this one (taken
from an Ubuntu guest):
</p>

<p>
<img src="ubuntu-power-dlg.png" width="532" height="450"
  longdesc="Ubuntu power dialog" />
</p>

<p>
The precise action taken depends on:
</p>

<ul>
<li> the guest </li>
<li> how the guest has been configured to react to ACPI events </li>
<li> if the guest is listening to ACPI at all
  (it may require that an ACPI daemon is started) </li>
<li> whether the guest is listening or has crashed, is busy &amp;c. </li>
</ul>

<p>
If a guest won't shut down or reboot, it is usually caused
by a problem with ACPI and/or guest configuration.  Eventually
you may need to use the <q>Force Off</q> option on recalcitrant
guests.
</p>

[% END %]

[% END -%]