D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
usr
/
share
/
doc
/
qemu-guest-agent
/
Filename :
qemu-ga.html
back
Copy
<!DOCTYPE html> <html class="writer-html5" lang="en" data-content_root="../"> <head> <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>QEMU Guest Agent — QEMU Debian 1:10.2.1+ds-1ubuntu3.1 documentation</title> <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=03e43079" /> <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=98b44b8a" /> <link rel="stylesheet" type="text/css" href="../_static/theme_overrides.css?v=b3ae9cc8" /> <link rel="shortcut icon" href="../_static/qemu_32x32.png"/> <script src="../_static/jquery.js?v=958b65b0"></script> <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="../_static/documentation_options.js?v=a0bc177d"></script> <script src="../_static/doctools.js?v=9bcbadda"></script> <script src="../_static/sphinx_highlight.js?v=dc90522c"></script> <script src="../_static/custom.js?v=2ab9f71d"></script> <script src="../_static/js/theme.js"></script> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="next" title="QEMU Guest Agent Protocol Reference" href="qemu-ga-ref.html" /> <link rel="prev" title="QEMU Machine Protocol Specification" href="qmp-spec.html" /> </head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" style="background: #802400" > <a href="../index.html" class="icon icon-home"> QEMU <img src="../_static/qemu_128x128.png" class="logo" alt="Logo"/> </a> <div role="search"> <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> <p class="caption" role="heading"><span class="caption-text">Contents:</span></p> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="../about/index.html">About QEMU</a></li> <li class="toctree-l1"><a class="reference internal" href="../system/index.html">System Emulation</a></li> <li class="toctree-l1"><a class="reference internal" href="../user/index.html">User Mode Emulation</a></li> <li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Tools</a></li> <li class="toctree-l1 current"><a class="reference internal" href="index.html">System Emulation Management and Interoperability</a><ul class="current"> <li class="toctree-l2"><a class="reference internal" href="barrier.html">Barrier client protocol</a></li> <li class="toctree-l2"><a class="reference internal" href="bitmaps.html">Dirty Bitmaps and Incremental Backup</a></li> <li class="toctree-l2"><a class="reference internal" href="dbus.html">D-Bus</a></li> <li class="toctree-l2"><a class="reference internal" href="dbus-vmstate.html">D-Bus VMState</a></li> <li class="toctree-l2"><a class="reference internal" href="dbus-display.html">D-Bus display</a></li> <li class="toctree-l2"><a class="reference internal" href="live-block-operations.html">Live Block Device Operations</a></li> <li class="toctree-l2"><a class="reference internal" href="nbd.html">QEMU NBD protocol support</a></li> <li class="toctree-l2"><a class="reference internal" href="parallels.html">Parallels Expandable Image File Format</a></li> <li class="toctree-l2"><a class="reference internal" href="prl-xml.html">Parallels Disk Format</a></li> <li class="toctree-l2"><a class="reference internal" href="qcow2.html">Qcow2 Image File Format</a></li> <li class="toctree-l2"><a class="reference internal" href="qed_spec.html">QED Image File Format Specification</a></li> <li class="toctree-l2"><a class="reference internal" href="pr-helper.html">Persistent reservation helper protocol</a></li> <li class="toctree-l2"><a class="reference internal" href="qmp-spec.html">QEMU Machine Protocol Specification</a></li> <li class="toctree-l2 current"><a class="current reference internal" href="#">QEMU Guest Agent</a><ul> <li class="toctree-l3"><a class="reference internal" href="#synopsis">Synopsis</a></li> <li class="toctree-l3"><a class="reference internal" href="#description">Description</a></li> <li class="toctree-l3"><a class="reference internal" href="#options">Options</a></li> <li class="toctree-l3"><a class="reference internal" href="#files">Files</a></li> <li class="toctree-l3"><a class="reference internal" href="#see-also">See also</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="qemu-ga-ref.html">QEMU Guest Agent Protocol Reference</a></li> <li class="toctree-l2"><a class="reference internal" href="qemu-qmp-ref.html">QEMU QMP Reference Manual</a></li> <li class="toctree-l2"><a class="reference internal" href="qemu-storage-daemon-qmp-ref.html">QEMU Storage Daemon QMP Reference Manual</a></li> <li class="toctree-l2"><a class="reference internal" href="vfio-user.html">vfio-user Protocol Specification</a></li> <li class="toctree-l2"><a class="reference internal" href="vhost-user.html">Vhost-user Protocol</a></li> <li class="toctree-l2"><a class="reference internal" href="vhost-user-gpu.html">Vhost-user-gpu Protocol</a></li> <li class="toctree-l2"><a class="reference internal" href="vhost-vdpa.html">Vhost-vdpa Protocol</a></li> <li class="toctree-l2"><a class="reference internal" href="virtio-balloon-stats.html">Virtio balloon memory statistics</a></li> <li class="toctree-l2"><a class="reference internal" href="vnc-ledstate-pseudo-encoding.html">VNC LED state Pseudo-encoding</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../specs/index.html">System Emulation Guest Hardware Specifications</a></li> <li class="toctree-l1"><a class="reference internal" href="../devel/index.html">Developer Information</a></li> <li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #802400" > <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="../index.html">QEMU</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item"><a href="index.html">System Emulation Management and Interoperability</a></li> <li class="breadcrumb-item active">QEMU Guest Agent</li> <li class="wy-breadcrumbs-aside"> <a href="https://gitlab.com/qemu-project/qemu/-/blob/master/docs/interop/qemu-ga.rst">View page source</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="qemu-guest-agent"> <span id="qemu-ga"></span><h1>QEMU Guest Agent<a class="headerlink" href="#qemu-guest-agent" title="Link to this heading"></a></h1> <section id="synopsis"> <h2>Synopsis<a class="headerlink" href="#synopsis" title="Link to this heading"></a></h2> <p><strong>qemu-ga</strong> [<em>OPTIONS</em>]</p> </section> <section id="description"> <h2>Description<a class="headerlink" href="#description" title="Link to this heading"></a></h2> <p>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:</p> <ul class="simple"> <li><p>get information from the guest</p></li> <li><p>set the guest's system time</p></li> <li><p>read/write a file</p></li> <li><p>sync and freeze the filesystems</p></li> <li><p>suspend the guest</p></li> <li><p>reconfigure guest local processors</p></li> <li><p>set user's password</p></li> <li><p>...</p></li> </ul> <p>qemu-ga will read a system configuration file on startup (located at <code class="docutils literal notranslate"><span class="pre">/etc/qemu</span></code><code class="docutils literal notranslate"><span class="pre">/qemu-ga.conf</span></code> 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).</p> <p>If an allowed RPCs list is defined in the configuration, then all RPCs will be blocked by default, except for the allowed list.</p> <p>If a blocked RPCs list is defined in the configuration, then all RPCs will be allowed by default, except for the blocked list.</p> <p>If both allowed and blocked RPCs lists are defined in the configuration, then all RPCs will be blocked by default, then the allowed list will be applied, followed by the blocked list.</p> <p>While filesystems are frozen, all except for a designated safe set of RPCs will blocked, regardless of what the general configuration declares.</p> </section> <section id="options"> <h2>Options<a class="headerlink" href="#options" title="Link to this heading"></a></h2> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-c"> <span id="cmdoption-qemu-ga-config"></span><span class="sig-name descname"><span class="pre">-c</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--config</span></span><span class="sig-prename descclassname"><span class="pre">=PATH</span></span><a class="headerlink" href="#cmdoption-qemu-ga-c" title="Link to this definition"></a></dt> <dd><p>Configuration file path (the default is <code class="docutils literal notranslate"><span class="pre">/etc/qemu</span></code><code class="docutils literal notranslate"><span class="pre">/qemu-ga.conf</span></code>, unless overridden by the QGA_CONF environment variable)</p> </dd></dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-m"> <span id="cmdoption-qemu-ga-method"></span><span class="sig-name descname"><span class="pre">-m</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--method</span></span><span class="sig-prename descclassname"><span class="pre">=METHOD</span></span><a class="headerlink" href="#cmdoption-qemu-ga-m" title="Link to this definition"></a></dt> <dd><p>Transport method: one of <code class="docutils literal notranslate"><span class="pre">unix-listen</span></code>, <code class="docutils literal notranslate"><span class="pre">virtio-serial</span></code>, or <code class="docutils literal notranslate"><span class="pre">isa-serial</span></code>, or <code class="docutils literal notranslate"><span class="pre">vsock-listen</span></code> (<code class="docutils literal notranslate"><span class="pre">virtio-serial</span></code> is the default).</p> </dd></dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-p"> <span id="cmdoption-qemu-ga-path"></span><span class="sig-name descname"><span class="pre">-p</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--path</span></span><span class="sig-prename descclassname"><span class="pre">=PATH</span></span><a class="headerlink" href="#cmdoption-qemu-ga-p" title="Link to this definition"></a></dt> <dd><p>Device/socket path (the default for virtio-serial is <code class="docutils literal notranslate"><span class="pre">/dev/virtio-ports/org.qemu.guest_agent.0</span></code>, the default for isa-serial is <code class="docutils literal notranslate"><span class="pre">/dev/ttyS0</span></code>). Socket addresses for vsock-listen are written as <code class="docutils literal notranslate"><span class="pre"><cid>:<port></span></code>.</p> </dd></dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-l"> <span id="cmdoption-qemu-ga-logfile"></span><span class="sig-name descname"><span class="pre">-l</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--logfile</span></span><span class="sig-prename descclassname"><span class="pre">=PATH</span></span><a class="headerlink" href="#cmdoption-qemu-ga-l" title="Link to this definition"></a></dt> <dd><p>Set log file path (default is stderr).</p> </dd></dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-f"> <span id="cmdoption-qemu-ga-pidfile"></span><span class="sig-name descname"><span class="pre">-f</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--pidfile</span></span><span class="sig-prename descclassname"><span class="pre">=PATH</span></span><a class="headerlink" href="#cmdoption-qemu-ga-f" title="Link to this definition"></a></dt> <dd><p>Specify pid file (default is <code class="docutils literal notranslate"><span class="pre">/var/run/qemu-ga.pid</span></code>).</p> </dd></dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-F"> <span id="cmdoption-qemu-ga-fsfreeze-hook"></span><span class="sig-name descname"><span class="pre">-F</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--fsfreeze-hook</span></span><span class="sig-prename descclassname"><span class="pre">=PATH</span></span><a class="headerlink" href="#cmdoption-qemu-ga-F" title="Link to this definition"></a></dt> <dd><p>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 <code class="docutils literal notranslate"><span class="pre">/etc/qemu</span></code><code class="docutils literal notranslate"><span class="pre">/fsfreeze-hook</span></code>). If using -F with an argument, do not follow -F with a space (for example: <code class="docutils literal notranslate"><span class="pre">-F/var/run/fsfreezehook.sh</span></code>).</p> </dd></dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-t"> <span id="cmdoption-qemu-ga-statedir"></span><span class="sig-name descname"><span class="pre">-t</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--statedir</span></span><span class="sig-prename descclassname"><span class="pre">=PATH</span></span><a class="headerlink" href="#cmdoption-qemu-ga-t" title="Link to this definition"></a></dt> <dd><p>Specify the directory to store state information (absolute paths only, default is <code class="docutils literal notranslate"><span class="pre">/var/run</span></code>).</p> </dd></dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-v"> <span id="cmdoption-qemu-ga-verbose"></span><span class="sig-name descname"><span class="pre">-v</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--verbose</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-qemu-ga-v" title="Link to this definition"></a></dt> <dd><p>Log extra debugging information.</p> </dd></dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-V"> <span id="cmdoption-qemu-ga-version"></span><span class="sig-name descname"><span class="pre">-V</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--version</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-qemu-ga-V" title="Link to this definition"></a></dt> <dd><p>Print version information and exit.</p> </dd></dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-d"> <span id="cmdoption-qemu-ga-daemon"></span><span class="sig-name descname"><span class="pre">-d</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--daemon</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-qemu-ga-d" title="Link to this definition"></a></dt> <dd><p>Daemonize after startup (detach from terminal).</p> </dd></dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-b"> <span id="cmdoption-qemu-ga-block-rpcs"></span><span class="sig-name descname"><span class="pre">-b</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--block-rpcs</span></span><span class="sig-prename descclassname"><span class="pre">=LIST</span></span><a class="headerlink" href="#cmdoption-qemu-ga-b" title="Link to this definition"></a></dt> <dd><p>Comma-separated list of RPCs to disable (no spaces, use <code class="docutils literal notranslate"><span class="pre">--block-rpcs=help</span></code> to list available RPCs).</p> </dd></dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-a"> <span id="cmdoption-qemu-ga-allow-rpcs"></span><span class="sig-name descname"><span class="pre">-a</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--allow-rpcs</span></span><span class="sig-prename descclassname"><span class="pre">=LIST</span></span><a class="headerlink" href="#cmdoption-qemu-ga-a" title="Link to this definition"></a></dt> <dd><p>Comma-separated list of RPCs to enable (no spaces, use <code class="docutils literal notranslate"><span class="pre">--allow-rpcs=help</span></code> to list available RPCs).</p> </dd></dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-D"> <span id="cmdoption-qemu-ga-dump-conf"></span><span class="sig-name descname"><span class="pre">-D</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--dump-conf</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-qemu-ga-D" title="Link to this definition"></a></dt> <dd><p>Dump the configuration in a format compatible with <code class="docutils literal notranslate"><span class="pre">qemu-ga.conf</span></code> and exit.</p> </dd></dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-qemu-ga-h"> <span id="cmdoption-qemu-ga-help"></span><span class="sig-name descname"><span class="pre">-h</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--help</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-qemu-ga-h" title="Link to this definition"></a></dt> <dd><p>Display this help and exit.</p> </dd></dl> </section> <section id="files"> <h2>Files<a class="headerlink" href="#files" title="Link to this heading"></a></h2> <p>The syntax of the <code class="docutils literal notranslate"><span class="pre">qemu-ga.conf</span></code> configuration file follows the Desktop Entry Specification, here is a quick summary: it consists of groups of key-value pairs, interspersed with comments.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># qemu-ga configuration sample</span> <span class="p">[</span><span class="n">general</span><span class="p">]</span> <span class="n">daemonize</span> <span class="o">=</span> <span class="mi">0</span> <span class="n">pidfile</span> <span class="o">=</span> <span class="o">/</span><span class="n">var</span><span class="o">/</span><span class="n">run</span><span class="o">/</span><span class="n">qemu</span><span class="o">-</span><span class="n">ga</span><span class="o">.</span><span class="n">pid</span> <span class="n">verbose</span> <span class="o">=</span> <span class="mi">0</span> <span class="n">method</span> <span class="o">=</span> <span class="n">virtio</span><span class="o">-</span><span class="n">serial</span> <span class="n">path</span> <span class="o">=</span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">virtio</span><span class="o">-</span><span class="n">ports</span><span class="o">/</span><span class="n">org</span><span class="o">.</span><span class="n">qemu</span><span class="o">.</span><span class="n">guest_agent</span><span class="mf">.0</span> <span class="n">statedir</span> <span class="o">=</span> <span class="o">/</span><span class="n">var</span><span class="o">/</span><span class="n">run</span> </pre></div> </div> <p>The list of keys follows the command line options:</p> <table class="docutils align-default"> <thead> <tr class="row-odd"><th class="head"><p>Key</p></th> <th class="head"><p>Key type</p></th> </tr> </thead> <tbody> <tr class="row-even"><td><p>daemon</p></td> <td><p>boolean</p></td> </tr> <tr class="row-odd"><td><p>method</p></td> <td><p>string</p></td> </tr> <tr class="row-even"><td><p>path</p></td> <td><p>string</p></td> </tr> <tr class="row-odd"><td><p>logfile</p></td> <td><p>string</p></td> </tr> <tr class="row-even"><td><p>pidfile</p></td> <td><p>string</p></td> </tr> <tr class="row-odd"><td><p>fsfreeze-hook</p></td> <td><p>string</p></td> </tr> <tr class="row-even"><td><p>statedir</p></td> <td><p>string</p></td> </tr> <tr class="row-odd"><td><p>verbose</p></td> <td><p>boolean</p></td> </tr> <tr class="row-even"><td><p>block-rpcs</p></td> <td><p>string list</p></td> </tr> <tr class="row-odd"><td><p>allow-rpcs</p></td> <td><p>string list</p></td> </tr> </tbody> </table> </section> <section id="see-also"> <h2>See also<a class="headerlink" href="#see-also" title="Link to this heading"></a></h2> <p><em class="manpage">qemu(1)</em></p> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="qmp-spec.html" class="btn btn-neutral float-left" title="QEMU Machine Protocol Specification" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> <a href="qemu-ga-ref.html" class="btn btn-neutral float-right" title="QEMU Guest Agent Protocol Reference" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> </div> <hr/> <div role="contentinfo"> <p>© Copyright 2025, The QEMU Project Developers.</p> </div> Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. <!-- Empty para to force a blank line after "Built with Sphinx ..." --> <p></p> <p>This documentation is for QEMU version 10.2.1.</p> <p><a href="../about/license.html">QEMU and this manual are released under the GNU General Public License, version 2.</a></p> </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>