One Hat Cyber Team

Edit File: qemu-ga.html

<!DOCTYPE html>

 <html class="no-js" lang="en" > 
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>QEMU Guest Agent &mdash; QEMU qemu-kvm-6.2.0-53.module+el8.10.0+2055+8eb7870b.4 documentation</title>

</head>

<a href="../index.html" class="icon icon-home"> QEMU

</div>

<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <p class="caption"><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="live-block-operations.html">Live Block Device Operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="pr-helper.html">Persistent reservation helper protocol</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="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>
</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>
</ul>

</div>
      </div>
    </nav>

<ul class="wy-breadcrumbs">
    
      <li><a href="../index.html">Docs</a> &raquo;</li>
        
          <li><a href="index.html">System Emulation Management and Interoperability</a> &raquo;</li>
        
      <li>QEMU Guest Agent</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            
              <a href="https://gitlab.com/qemu-project/qemu/blob/master/docs/interop/qemu-ga.rst" class="fa fa-gitlab"> Edit on GitLab</a>
            
          
        
      </li>
    
  </ul>

<hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="qemu-guest-agent">
<h1>QEMU Guest Agent<a class="headerlink" href="#qemu-guest-agent" title="Permalink to this headline">¶</a></h1>
<div class="section" id="synopsis">
<h2>Synopsis<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
<p><strong>qemu-ga</strong> [<em>OPTIONS</em>]</p>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</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>get information from the guest</li>
<li>set the guest’s system time</li>
<li>read/write a file</li>
<li>sync and freeze the filesystems</li>
<li>suspend the guest</li>
<li>reconfigure guest local processors</li>
<li>set user’s password</li>
<li>…</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-kvm</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>
</div>
<div class="section" id="options">
<h2>Options<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
<dl class="option">
<dt id="cmdoption-qemu-ga-m">
<code class="descname">-m</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--method</code><code class="descclassname">=METHOD</code><a class="headerlink" href="#cmdoption-qemu-ga-m" title="Permalink 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="option">
<dt id="cmdoption-qemu-ga-p">
<code class="descname">-p</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--path</code><code class="descclassname">=PATH</code><a class="headerlink" href="#cmdoption-qemu-ga-p" title="Permalink 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">&lt;cid&gt;:&lt;port&gt;</span></code>.</p>
</dd></dl>

<dl class="option">
<dt id="cmdoption-qemu-ga-l">
<code class="descname">-l</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--logfile</code><code class="descclassname">=PATH</code><a class="headerlink" href="#cmdoption-qemu-ga-l" title="Permalink to this definition">¶</a></dt>
<dd><p>Set log file path (default is stderr).</p>
</dd></dl>

<dl class="option">
<dt id="cmdoption-qemu-ga-f">
<code class="descname">-f</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--pidfile</code><code class="descclassname">=PATH</code><a class="headerlink" href="#cmdoption-qemu-ga-f" title="Permalink 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="option">
<dt id="cmdoption-qemu-ga-fsfreeze-hook">
<code class="descname">-F</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--fsfreeze-hook</code><code class="descclassname">=PATH</code><a class="headerlink" href="#cmdoption-qemu-ga-fsfreeze-hook" title="Permalink 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-kvm</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="option">
<dt id="cmdoption-qemu-ga-t">
<code class="descname">-t</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--statedir</code><code class="descclassname">=PATH</code><a class="headerlink" href="#cmdoption-qemu-ga-t" title="Permalink 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="option">
<dt id="cmdoption-qemu-ga-v">
<code class="descname">-v</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--verbose</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-qemu-ga-v" title="Permalink to this definition">¶</a></dt>
<dd><p>Log extra debugging information.</p>
</dd></dl>

<dl class="option">
<dt id="cmdoption-qemu-ga-version">
<code class="descname">-V</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--version</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-qemu-ga-version" title="Permalink to this definition">¶</a></dt>
<dd><p>Print version information and exit.</p>
</dd></dl>

<dl class="option">
<dt id="cmdoption-qemu-ga-d">
<code class="descname">-d</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--daemon</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-qemu-ga-d" title="Permalink to this definition">¶</a></dt>
<dd><p>Daemonize after startup (detach from terminal).</p>
</dd></dl>

<dl class="option">
<dt id="cmdoption-qemu-ga-b">
<code class="descname">-b</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--blacklist</code><code class="descclassname">=LIST</code><a class="headerlink" href="#cmdoption-qemu-ga-b" title="Permalink to this definition">¶</a></dt>
<dd><p>Comma-separated list of RPCs to disable (no spaces, <code class="docutils literal notranslate"><span class="pre">?</span></code> to list
available RPCs).</p>
</dd></dl>

<dl class="option">
<dt id="cmdoption-qemu-ga-dump-conf">
<code class="descname">-D</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--dump-conf</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-qemu-ga-dump-conf" title="Permalink 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="option">
<dt id="cmdoption-qemu-ga-h">
<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-qemu-ga-h" title="Permalink to this definition">¶</a></dt>
<dd><p>Display this help and exit.</p>
</dd></dl>

</div>
<div class="section" id="files">
<h2>Files<a class="headerlink" href="#files" title="Permalink to this headline">¶</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="o">.</span><span class="mi">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 border="1" class="docutils">
<colgroup>
<col width="54%" />
<col width="46%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Key</th>
<th class="head">Key type</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>daemon</td>
<td>boolean</td>
</tr>
<tr class="row-odd"><td>method</td>
<td>string</td>
</tr>
<tr class="row-even"><td>path</td>
<td>string</td>
</tr>
<tr class="row-odd"><td>logfile</td>
<td>string</td>
</tr>
<tr class="row-even"><td>pidfile</td>
<td>string</td>
</tr>
<tr class="row-odd"><td>fsfreeze-hook</td>
<td>string</td>
</tr>
<tr class="row-even"><td>statedir</td>
<td>string</td>
</tr>
<tr class="row-odd"><td>verbose</td>
<td>boolean</td>
</tr>
<tr class="row-even"><td>blacklist</td>
<td>string list</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="see-also">
<h2>See also<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
<p><em class="manpage">qemu(1)</em></p>
</div>
</div>

</div>
           
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <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"></span></a>
      
      
        <a href="pr-helper.html" class="btn btn-neutral" title="Persistent reservation helper protocol" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>

<hr/>

</p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.

<p></p>

<p>This documentation is for QEMU version 6.2.0.</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>

</body>
</html>