d99744c3df
The XML root element of Docbook XML files should match the following format: <ELEMENT xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="THE_XML_ID_OF_THE_ELEMENT"> Change-Id: I95a6f36d6887af952257a800e3359d53ac1f895a
117 lines
6.4 KiB
XML
117 lines
6.4 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
version="5.0"
|
|
xml:id="root-wrap-reference">
|
|
<title>Secure with root wrappers</title>
|
|
<para>The root wrapper enables an unprivileged user to run a number of Compute actions as the
|
|
root user in the safest manner possible. Historically, Compute used a specific
|
|
<filename>sudoers</filename> file that listed every command that the Compute user was
|
|
allowed to run, and used <command>sudo</command> to run that command as
|
|
<literal>root</literal>. However this was difficult to maintain (the
|
|
<filename>sudoers</filename> file was in packaging), and did not enable complex
|
|
filtering of parameters (advanced filters). The rootwrap was designed to solve those
|
|
issues.</para>
|
|
<simplesect>
|
|
<title>How rootwrap works</title>
|
|
<para>Instead of calling <command>sudo make me a sandwich</command>, Compute services start
|
|
with a <command>nova-rootwrap</command> call; for example, <command>sudo nova-rootwrap
|
|
/etc/nova/rootwrap.conf make me a sandwich</command>. A generic sudoers entry lets
|
|
the Compute user run <command>nova-rootwrap</command> as root. The
|
|
<command>nova-rootwrap</command> code looks for filter definition directories in its
|
|
configuration file, and loads command filters from them. Then it checks if the command
|
|
requested by Compute matches one of those filters, in which case it executes the command
|
|
(as root). If no filter matches, it denies the request.</para>
|
|
<note><para>To use <command>nova-rootwrap</command>, you must be aware of the issues with using NFS and
|
|
root-owned files. The NFS share must be configured with the
|
|
<option>no_root_squash</option> option enabled.</para>
|
|
</note>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Security model</title>
|
|
<para>The escalation path is fully controlled by the root user. A sudoers entry (owned by
|
|
root) allows Compute to run (as root) a specific rootwrap executable, and only with a
|
|
specific configuration file (which should be owned by root).
|
|
<command>nova-rootwrap</command> imports the Python modules it needs from a cleaned
|
|
(and system-default) <replaceable>PYTHONPATH</replaceable>. The configuration file (also
|
|
root-owned) points to root-owned filter definition directories, which contain root-owned
|
|
filters definition files. This chain ensures that the Compute user itself is not in
|
|
control of the configuration or modules used by the <command>nova-rootwrap</command>
|
|
executable.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Details of rootwrap.conf</title>
|
|
<para>You configure <command>nova-rootwrap</command> in the
|
|
<filename>rootwrap.conf</filename> file. Because it's in the trusted security path,
|
|
it must be owned and writable by only the root user. The file's location is specified
|
|
both in the sudoers entry and in the <filename>nova.conf</filename> configuration file
|
|
with the <code>rootwrap_config=entry</code>.</para>
|
|
<para>The <filename>rootwrap.conf</filename> file uses an INI file format with these
|
|
sections and parameters:</para>
|
|
<table rules="all" frame="border"
|
|
xml:id="rootwrap-conf-table-filter-path" width="100%">
|
|
<caption>rootwrap.conf configuration options</caption>
|
|
<col width="50%"/>
|
|
<col width="50%"/>
|
|
<thead>
|
|
<tr>
|
|
<td><para>Configuration option=Default
|
|
value</para></td>
|
|
<td><para>(Type) Description</para></td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><para>[DEFAULT]</para>
|
|
<para>filters_path=/etc/nova/rootwrap.d,/usr/share/nova/rootwrap
|
|
</para></td>
|
|
<td><para>(ListOpt) Comma-separated list of
|
|
directories containing filter definition
|
|
files. Defines where filters for root wrap
|
|
are stored. Directories defined on this
|
|
line should all exist, be owned and
|
|
writable only by the root
|
|
user.</para></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Details of .filters files</title>
|
|
<para>Filters definition files contain lists of filters that
|
|
<command>nova-rootwrap</command> will use to allow or deny a specific command. They
|
|
are generally suffixed by .filters. Since they are in the trusted security path, they
|
|
need to be owned and writable only by the root user. Their location is specified in the
|
|
<filename>rootwrap.conf</filename> file.</para>
|
|
<para>Filter definition files use an INI file format with a [Filters] section and several
|
|
lines, each with a unique parameter name (different for each filter that you
|
|
define):</para>
|
|
<table rules="all" frame="border"
|
|
xml:id="rootwrap-conf-table-filter-name" width="100%">
|
|
<caption>.filters configuration options</caption>
|
|
<col width="50%"/>
|
|
<col width="50%"/>
|
|
<thead>
|
|
<tr>
|
|
<td><para>Configuration option=Default
|
|
value</para></td>
|
|
<td><para>(Type) Description</para></td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><para>[Filters]</para>
|
|
<para>filter_name=kpartx: CommandFilter,
|
|
/sbin/kpartx, root</para></td>
|
|
<td><para>(ListOpt) Comma-separated list
|
|
containing first the Filter class to use,
|
|
followed by that Filter arguments (which
|
|
vary depending on the Filter class
|
|
selected).</para></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</simplesect>
|
|
</section>
|