[% topdir = "../.." -%]
[% PROCESS globals -%]
[% WRAPPER page
   title = "Starting and stopping VMs from the command line"
   h1 = "Starting and stopping VMs from the command line"
   section = "learning"
%]

<p>
<q>Lifecycle management</q> (which is a fancy way of
saying <q>starting and stopping virtual machines</q>) can be done
either <a href="../start-vm-with-virt-manager/">from virt-manager</a>
or directly from the command line or shell scripts
using <code>virsh</code>.
</p>

<p>
These commands generally require that you are root.  On
Fedora and Debian, do:
</p>

<pre>
su
</pre>

<p>
and type the root password.
</p>

<p>
On Ubuntu you can prefix each command with <code>sudo</code>,
or get a root shell first by doing:
</p>

<pre>
sudo bash
</pre>

<p>
<a href="../start-list-with-command-line/">List out the
virtual machines that you have available</a>.  You can
then substitute the name of one of your virtual machines
for generic <q>Guest</q> below.
</p>

[% WRAPPER h2 h2="Starting a virtual machine with virsh" anchor="start" %]

<p>
To start a virtual machine running, do:
</p>

<pre>
virsh start Guest
</pre>

<p>
where <q>Guest</q> is the name of the virtual machine.  Check
that it is running by
<a href="../start-list-with-command-line/">using <code>virsh list</code></a>
or connecting to the console with:
</p>

<pre>
virt-viewer Guest
</pre>

[% END %]

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

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

<h3>Pull the plug</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>
You can do this from <code>virsh</code> too using the
<code>virsh destroy</code> command, but be careful as the guest is
switched off with no warning and no chance to sync the disks:
</p>

<pre>
virsh destroy Guest
</pre>

<h3>ACPI</h3>

<p>
The more common option is to reboot or shutdown the guest:
</p>

<pre>
virsh reboot Guest
</pre>

<pre>
virsh shutdown Guest
</pre>

<p>
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>
Using the <code>virsh reboot</code> or <code>virsh shutdown</code>
commands is like pressing the virtual power button, and it 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 <code>virsh destroy</code> guests that don't
respond to ordinary events.
</p>

[% END %]

[% END -%]