This posting details how the public API should be enhanced

https://www.redhat.com/archives/libvir-list/2011-October/msg00137.html

I noticed some patches upstream in the last few days.  How's it going?

Moving to POST:

commit 17cfff6f17f17be4b66571be75d5870134e73668
Author:     Daniel P. Berrange <berrange>
AuthorDate: Wed Oct 5 18:31:57 2011 +0100
Commit:     Michal Privoznik <mprivozn>
CommitDate: Tue Jan 24 12:19:51 2012 +0100

    Allow choice of shutdown method via virsh
    
    Extend the 'shutdown' and 'reboot' methods so that they both
    accept a new argument
    
        --mode acpi|agent
    
    * tools/virsh.c: New args for shutdown/reboot
    * tools/virsh.pod: Document new args

commit fb52a399285713317629b28ea7aaf4b0b92e8f21
Author:     Daniel P. Berrange <berrange>
AuthorDate: Wed Oct 5 18:31:56 2011 +0100
Commit:     Michal Privoznik <mprivozn>
CommitDate: Tue Jan 24 12:19:51 2012 +0100

    Wire up QEMU agent to reboot/shutdown APIs
    
    This makes use of the QEMU guest agent to implement the
    virDomainShutdownFlags and virDomainReboot APIs. With
    no flags specified, it will prefer to use the agent, but
    fallback to ACPI. Explicit choice can be made by using
    a suitable flag
    
    * src/qemu/qemu_driver.c: Wire up use of agent

commit 0b7ddf9e7788958f0ced0de03572af25754324c8
Author:     Daniel P. Berrange <berrange>
AuthorDate: Wed Oct 5 18:31:55 2011 +0100
Commit:     Michal Privoznik <mprivozn>
CommitDate: Tue Jan 24 12:19:51 2012 +0100

    Add new virDomainShutdownFlags API
    
    Add a new API virDomainShutdownFlags and define:
    
        VIR_DOMAIN_SHUTDOWN_DEFAULT        = 0,
        VIR_DOMAIN_SHUTDOWN_ACPI_POWER_BTN = (1 << 0),
        VIR_DOMAIN_SHUTDOWN_GUEST_AGENT    = (1 << 1),
    
    Also define some flags for the reboot API
    
        VIR_DOMAIN_REBOOT_DEFAULT        = 0,
        VIR_DOMAIN_REBOOT_ACPI_POWER_BTN = (1 << 0),
        VIR_DOMAIN_REBOOT_GUEST_AGENT    = (1 << 1),
    
    Although these two APIs currently have the same flags, using
    separate enums allows them to expand separately in the future.
    
    Add stub impls of the new API for all existing drivers

commit c160ce3316852a797d7b06b4ee101233866e69a9
Author:     Daniel P. Berrange <berrange>
AuthorDate: Wed Oct 5 18:31:54 2011 +0100
Commit:     Michal Privoznik <mprivozn>
CommitDate: Tue Jan 24 12:19:51 2012 +0100

    QEMU guest agent support
    
    There is now a standard QEMU guest agent that can be installed
    and given a virtio serial channel
    
        <channel type='unix'>
          <source mode='bind' path='/var/lib/libvirt/qemu/f16x86_64.agent'/>
          <target type='virtio' name='org.qemu.guest_agent.0'/>
        </channel>
    
    The protocol that runs over the guest agent is JSON based and
    very similar to the JSON monitor. We can't use exactly the same
    code because there are some odd differences in the way messages
    and errors are structured. The qemu_agent.c file is based on
    a combination and simplification of qemu_monitor.c and
    qemu_monitor_json.c
    
    * src/qemu/qemu_agent.c, src/qemu/qemu_agent.h: Support for
      talking to the agent for shutdown
    * src/qemu/qemu_domain.c, src/qemu/qemu_domain.h: Add thread
      helpers for talking to the agent
    * src/qemu/qemu_process.c: Connect to agent whenever starting
      a guest
    * src/qemu/qemu_monitor_json.c: Make variable static

It seems the agent mode hasn't been supported on libvirt-0.9.10-0rc2.el6.x86_64 with qemu-kvm-0.12.1.2-2.211.el6.x86_64(QEMU PC emulator version 0.12.1), I can see the following error when reboot/shutdown a guest with 'agent' mode:

error: argument unsupported: QEMU guest agent is not configured

Maybe, I need to upgrade qemu to >=1.0 and agent >=1.1?

You need to configure qemu guest agent:

http://wiki.libvirt.org/page/Qemu_guest_agent

(In reply to comment #5)
> http://wiki.libvirt.org/page/Qemu_guest_agent

Michal, thanks. I will see it.

Hi Daniel and Michal, 
The guest can be successfully rebooted and shutdowned with 'acpi' mode, however, I need to execute reboot/shutdown second times for 'agent' mode, the operations will be valid, for first time, although virsh output says "Domain xx is being rebooted" or "Domain xx is being shutdown", but in fact, the information is fake/spurious, the guest is still running, then operations are valid for reboot/shutdown guest again, it's a expected result, right?

Created attachment 573909 [details]
LIBVIRT_DEBUG=1 virsh shutdown --mode agent rhel6

Tested with 
libvirt-0.9.10-9.el6
qemu-kvm-0.12.1.2-2.265.el6
qemu-guest-agent-0.12.1.2-2.265.el6

Two issue here:
a. guest cann't shutdown with --mode agent
b. "virsh shutdown" was locked after interrupt the command with Ctrl+C

1.update xml for guest:
<channel type='unix'>
      <source mode='bind' path='/var/lib/libvirt/qemu/rhel6.agent'/>
      <target type='virtio' name='org.qemu.guest_agent.0'/>
    </channel>

2.install qemu-guest-agent in guest.

3.# virsh shutdown --mode agent rhel6
^C

Long time no respons..., then interrupt with Ctrl+C

# virsh list --all
 Id    Name                           State
----------------------------------------------------
 36    rhel6                          running

4. "virsh shutdown" was locked, destroy can work well before libvirtd restart.

# virsh shutdown --mode acpi rhel6

error: Failed to shutdown domain rhel6
error: Timed out during operation: cannot acquire state change lock

# virsh shutdown --mode agent rhel6
error: Failed to shutdown domain rhel6
error: Timed out during operation: cannot acquire state change lock

5. # service libvirtd restart
Stopping libvirtd daemon:                                  [  OK  ]
Starting libvirtd daemon:                                  [  OK  ]

# virsh shutdown --mode acpi rhel6
Domain rhel6 is being shutdown

According to comment 11, verified PASS with 
libvirt-0.9.10-9.el6
qemu-kvm-0.12.1.2-2.265.el6
qemu-guest-agent-0.12.1.2-2.265.el6

start guest-ga in guest:
# /etc/rc.d/init.d/qemu-ga start

in host:
# virsh shutdown --mode agent rhel6
Domain rhel6 is being shutdown

# virsh list --all
 Id    Name                           State
----------------------------------------------------
 40    rhel6                          in shutdown

# virsh list --all
 Id    Name                           State
----------------------------------------------------
 -     rhel6                          shut off

# virsh start rhel6

# virsh reboot --mode agent rhel6
Domain rhel6 is being rebooted

the guest reboot successfully.

    Technical note added. If any revisions are required, please edit the "Technical Notes" field
    accordingly. All revisions will be proofread by the Engineering Content Services team.
    
    New Contents:
Cause: Management application may want guest to shutdown or reboot. However, it was implemented by issuing ACPI events into the guest which may have decided to ignore them.
Consequence: Management application was unable to reboot such guest.
Change: Libvirt implemented support for guest-agent. It's a small application within guest which will call 'shutdown' or 'reboot' for us (in this case) when it has been told to.
Result: Despite guest ignoring ACPI events, it can be shutdown or rebooted at will.

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

http://rhn.redhat.com/errata/RHSA-2012-0748.html