111 lines
5.9 KiB
XML
111 lines
5.9 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 rootwrap</title>
|
|
<para>Rootwrap allows unprivileged users to safely run Compute actions
|
|
as the root user. Compute previously used <command>sudo</command> for
|
|
this purpose, but this was difficult to maintain, and did not allow
|
|
advanced filters. The <command>rootwrap</command> command replaces
|
|
<command>sudo</command> for Compute.</para>
|
|
<para>To use rootwrap, prefix the Compute command with
|
|
<command>nova-rootwrap</command>. For example:</para>
|
|
<screen><prompt>$</prompt> <userinput>sudo nova-rootwrap /etc/nova/rootwrap.conf <replaceable>command</replaceable></userinput></screen>
|
|
<para>
|
|
A generic <filename>sudoers</filename> 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. It then checks if the command requested by Compute matches one of
|
|
those filters and, if so, executes the command (as root). If no filter
|
|
matches, it denies the request.</para>
|
|
<note><para>Be aware of issues with using NFS and root-owned files. The
|
|
NFS share must be configured with the <option>no_root_squash</option>
|
|
option enabled, in order for rootwrap to work correctly.</para>
|
|
</note>
|
|
<para>Rootwrap is fully controlled by the root user. The root user owns
|
|
the sudoers entry which allows Compute to run a specific rootwrap
|
|
executable as root, and only with a specific configuration file (which
|
|
should also be owned by root). The <command>nova-rootwrap</command>
|
|
command imports the Python modules it needs from a cleaned,
|
|
system-default <replaceable>PYTHONPATH</replaceable>. The root-owned
|
|
configuration file 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>
|
|
<para>Rootwrap is configured using 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 in both
|
|
the sudoers entry and in the <filename>nova.conf</filename> configuration
|
|
file with the <literal>rootwrap_config=entry</literal> parameter.</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 rootwrap filters are
|
|
stored. Directories defined on this line should all exist, and be
|
|
owned and writable only by the root user.</para></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<para>If the root wrapper is not performing correctly, you can
|
|
add a workaround option into the <filename>nova.conf</filename>
|
|
configuration file. This workaround re-configures the
|
|
root wrapper configuration to fall back to running commands as
|
|
sudo, and is a Kilo release feature.</para>
|
|
<para>Including this workaround in your configuration file
|
|
safeguards your environment from issues that can impair root
|
|
wrapper performance. Tool changes that have impacted
|
|
<link xlink:href="https://git.openstack.org/cgit/openstack-dev/pbr/">Python Build Reasonableness (PBR)</link>,
|
|
for example, are a known issue that affects
|
|
root wrapper performance.</para>
|
|
<para>To set up this workaround, configure the <parameter>disable_rootwrap</parameter>
|
|
option in the <option>[workaround]</option> section
|
|
of the <filename>nova.conf</filename> configuration file.</para>
|
|
<para>The filters definition files contain lists of filters that rootwrap
|
|
will use to allow or deny a specific command. They are generally
|
|
suffixed by <literal>.filters</literal>. 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
|
|
<literal>[Filters]</literal> section and several lines, each with a
|
|
unique parameter name, which should be different for each filter 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 the filter class
|
|
to use, followed by the Filter arguments (which vary depending
|
|
on the Filter class selected).</para></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|