Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into staging

[mirror_qemu.git] / qemu-ga.texi

@example
@c man begin SYNOPSIS
@command{qemu-ga} [@var{OPTIONS}]
@c man end
@end example

@c man begin DESCRIPTION

The QEMU Guest Agent is a daemon intended to be run within virtual
machines. It allows the hypervisor host to perform various operations
in the guest, such as:

@itemize
@item
get information from the guest
@item
set the guest's system time
@item
read/write a file
@item
sync and freeze the filesystems
@item
suspend the guest
@item
reconfigure guest local processors
@item
set user's password
@item
...
@end itemize

qemu-ga will read a system configuration file on startup (located at
@file{@value{CONFDIR}/qemu-ga.conf} by default), then parse remaining
configuration options on the command line. For the same key, the last
option wins, but the lists accumulate (see below for configuration
file format).

@c man end

@c man begin OPTIONS
@table @option
@item -m, --method=@var{method}
  Transport method: one of @samp{unix-listen}, @samp{virtio-serial}, or
  @samp{isa-serial} (@samp{virtio-serial} is the default).

@item -p, --path=@var{path}
  Device/socket path (the default for virtio-serial is
  @samp{/dev/virtio-ports/org.qemu.guest_agent.0},
  the default for isa-serial is @samp{/dev/ttyS0})

@item -l, --logfile=@var{path}
  Set log file path (default is stderr).

@item -f, --pidfile=@var{path}
  Specify pid file (default is @samp{/var/run/qemu-ga.pid}).

@item -F, --fsfreeze-hook=@var{path}
  Enable fsfreeze hook. Accepts an optional argument that specifies
  script to run on freeze/thaw. Script will be called with
  'freeze'/'thaw' arguments accordingly (default is
  @samp{@value{CONFDIR}/fsfreeze-hook}). If using -F with an argument, do
  not follow -F with a space (for example:
  @samp{-F/var/run/fsfreezehook.sh}).

@item -t, --statedir=@var{path}
  Specify the directory to store state information (absolute paths only,
  default is @samp{/var/run}).

@item -v, --verbose
  Log extra debugging information.

@item -V, --version
  Print version information and exit.

@item -d, --daemon
  Daemonize after startup (detach from terminal).

@item -b, --blacklist=@var{list}
  Comma-separated list of RPCs to disable (no spaces, @samp{?} to list
  available RPCs).

@item -D, --dump-conf
  Dump the configuration in a format compatible with @file{qemu-ga.conf}
  and exit.

@item -h, --help
  Display this help and exit.
@end table

@c man end

@c man begin FILES

The syntax of the @file{qemu-ga.conf} configuration file follows the
Desktop Entry Specification, here is a quick summary: it consists of
groups of key-value pairs, interspersed with comments.

@example
# qemu-ga configuration sample
[general]
daemonize = 0
pidfile = /var/run/qemu-ga.pid
verbose = 0
method = virtio-serial
path = /dev/virtio-ports/org.qemu.guest_agent.0
statedir = /var/run
@end example

The list of keys follows the command line options:
@table @option
@item daemon= boolean
@item method= string
@item path= string
@item logfile= string
@item pidfile= string
@item fsfreeze-hook= string
@item statedir= string
@item verbose= boolean
@item blacklist= string list
@end table

@c man end

@ignore

@setfilename qemu-ga
@settitle QEMU Guest Agent

@c man begin AUTHOR
Michael Roth <mdroth@linux.vnet.ibm.com>
@c man end

@c man begin SEEALSO
qemu(1)
@c man end

@end ignore