Mini Shell
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>QEMU persistent reservation helper — QEMU qemu-kvm-6.2.0-53.module_el8.10.0+4110+4a319788.6 documentation</title>
<link rel="shortcut icon" href="../_static/qemu_32x32.png"/>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="QEMU SystemTap trace tool" href="qemu-trace-stap.html" />
<link rel="prev" title="QEMU Disk Network Block Device Server" href="qemu-nbd.html" />
<script src="../_static/js/modernizr.min.js"></script>
</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">
<a href="../index.html" class="icon icon-home"> QEMU
<img src="../_static/qemu_128x128.png" class="logo" alt="Logo"/>
</a>
<div class="version">
6.2.0
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="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="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 current"><a class="reference internal" href="index.html">Tools</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="qemu-img.html">QEMU disk image utility</a></li>
<li class="toctree-l2"><a class="reference internal" href="qemu-storage-daemon.html">QEMU Storage Daemon</a></li>
<li class="toctree-l2"><a class="reference internal" href="qemu-nbd.html">QEMU Disk Network Block Device Server</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">QEMU persistent reservation helper</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>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="qemu-trace-stap.html">QEMU SystemTap trace tool</a></li>
<li class="toctree-l2"><a class="reference internal" href="virtfs-proxy-helper.html">QEMU 9p virtfs proxy filesystem helper</a></li>
<li class="toctree-l2"><a class="reference internal" href="virtiofsd.html">QEMU virtio-fs shared file system daemon</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../interop/index.html">System Emulation Management and Interoperability</a></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>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<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="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> »</li>
<li><a href="index.html">Tools</a> »</li>
<li>QEMU persistent reservation helper</li>
<li class="wy-breadcrumbs-aside">
<a href="https://gitlab.com/qemu-project/qemu/blob/master/docs/tools/qemu-pr-helper.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-persistent-reservation-helper">
<h1>QEMU persistent reservation helper<a class="headerlink" href="#qemu-persistent-reservation-helper" 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-pr-helper</strong> [<em>OPTION</em>]</p>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>Implements the persistent reservation helper for QEMU.</p>
<p>SCSI persistent reservations allow restricting access to block devices
to specific initiators in a shared storage setup. When implementing
clustering of virtual machines, it is a common requirement for virtual
machines to send persistent reservation SCSI commands. However,
the operating system restricts sending these commands to unprivileged
programs because incorrect usage can disrupt regular operation of the
storage fabric. QEMU’s SCSI passthrough devices <code class="docutils literal notranslate"><span class="pre">scsi-block</span></code>
and <code class="docutils literal notranslate"><span class="pre">scsi-generic</span></code> support passing guest persistent reservation
requests to a privileged external helper program. <strong class="program">qemu-pr-helper</strong>
is that external helper; it creates a socket which QEMU can
connect to to communicate with it.</p>
<p>If you want to run VMs in a setup like this, this helper should be
started as a system service, and you should read the QEMU manual
section on “persistent reservation managers” to find out how to
configure QEMU to connect to the socket created by
<strong class="program">qemu-pr-helper</strong>.</p>
<p>After connecting to the socket, <strong class="program">qemu-pr-helper</strong> can
optionally drop root privileges, except for those capabilities that
are needed for its operation.</p>
<p><strong class="program">qemu-pr-helper</strong> can also use the systemd socket activation
protocol. In this case, the systemd socket unit should specify a
Unix stream socket, like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">Socket</span><span class="p">]</span>
<span class="n">ListenStream</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">pr</span><span class="o">-</span><span class="n">helper</span><span class="o">.</span><span class="n">sock</span>
</pre></div>
</div>
</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-pr-helper-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-pr-helper-d" title="Permalink to this definition">¶</a></dt>
<dd><p>run in the background (and create a PID file)</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-qemu-pr-helper-q">
<code class="descname">-q</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--quiet</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-qemu-pr-helper-q" title="Permalink to this definition">¶</a></dt>
<dd><p>decrease verbosity</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-qemu-pr-helper-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-pr-helper-v" title="Permalink to this definition">¶</a></dt>
<dd><p>increase verbosity</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-qemu-pr-helper-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-pr-helper-f" title="Permalink to this definition">¶</a></dt>
<dd><p>PID file when running as a daemon. By default the PID file
is created in the system runtime state directory, for example
<code class="file docutils literal notranslate"><span class="pre">/var/run/qemu-pr-helper.pid</span></code>.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-qemu-pr-helper-k">
<code class="descname">-k</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--socket</code><code class="descclassname">=PATH</code><a class="headerlink" href="#cmdoption-qemu-pr-helper-k" title="Permalink to this definition">¶</a></dt>
<dd><p>path to the socket. By default the socket is created in
the system runtime state directory, for example
<code class="file docutils literal notranslate"><span class="pre">/var/run/qemu-pr-helper.sock</span></code>.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-qemu-pr-helper-t">
<code class="descname">-T</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--trace</code><code class="descclassname"> [[enable=]PATTERN][,events=FILE][,file=FILE]</code><a class="headerlink" href="#cmdoption-qemu-pr-helper-t" title="Permalink to this definition">¶</a></dt>
<dd><p>Specify tracing options.</p>
<p><code class="docutils literal notranslate"><span class="pre">[enable=]PATTERN</span></code></p>
<blockquote>
<div><p>Immediately enable events matching <em>PATTERN</em>
(either event name or a globbing pattern). This option is only
available if QEMU has been compiled with the <code class="docutils literal notranslate"><span class="pre">simple</span></code>, <code class="docutils literal notranslate"><span class="pre">log</span></code>
or <code class="docutils literal notranslate"><span class="pre">ftrace</span></code> tracing backend. To specify multiple events or patterns,
specify the <code class="xref std std-option docutils literal notranslate"><span class="pre">-trace</span></code> option multiple times.</p>
<p>Use <code class="xref std std-option docutils literal notranslate"><span class="pre">-trace</span> <span class="pre">help</span></code> to print a list of names of trace points.</p>
</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">events=FILE</span></code></p>
<blockquote>
<div>Immediately enable events listed in <em>FILE</em>.
The file must contain one event name (as listed in the <code class="docutils literal notranslate"><span class="pre">trace-events-all</span></code>
file) per line; globbing patterns are accepted too. This option is only
available if QEMU has been compiled with the <code class="docutils literal notranslate"><span class="pre">simple</span></code>, <code class="docutils literal notranslate"><span class="pre">log</span></code> or
<code class="docutils literal notranslate"><span class="pre">ftrace</span></code> tracing backend.</div></blockquote>
<p><code class="docutils literal notranslate"><span class="pre">file=FILE</span></code></p>
<blockquote>
<div>Log output traces to <em>FILE</em>.
This option is only available if QEMU has been compiled with
the <code class="docutils literal notranslate"><span class="pre">simple</span></code> tracing backend.</div></blockquote>
</dd></dl>
<dl class="option">
<dt id="cmdoption-qemu-pr-helper-u">
<code class="descname">-u</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--user</code><code class="descclassname">=USER</code><a class="headerlink" href="#cmdoption-qemu-pr-helper-u" title="Permalink to this definition">¶</a></dt>
<dd><p>user to drop privileges to</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-qemu-pr-helper-g">
<code class="descname">-g</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--group</code><code class="descclassname">=GROUP</code><a class="headerlink" href="#cmdoption-qemu-pr-helper-g" title="Permalink to this definition">¶</a></dt>
<dd><p>group to drop privileges to</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-qemu-pr-helper-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-pr-helper-h" title="Permalink to this definition">¶</a></dt>
<dd><p>Display a help message and exit.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-qemu-pr-helper-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-pr-helper-version" title="Permalink to this definition">¶</a></dt>
<dd><p>Display version information and exit.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="qemu-trace-stap.html" class="btn btn-neutral float-right" title="QEMU SystemTap trace tool" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="qemu-nbd.html" class="btn btn-neutral" title="QEMU Disk Network Block Device Server" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2021, The QEMU Project Developers.
</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>.
<!-- Empty para to force a blank line after "Built with Sphinx ..." -->
<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>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'qemu-kvm-6.2.0-53.module_el8.10.0+4110+4a319788.6',
LANGUAGE:'None',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: false,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>