.. _root-wrap-reference:

====================
Secure with rootwrap
====================

Rootwrap allows unprivileged users to safely run Compute actions as the
root user. Compute previously used :command:`sudo` for this purpose, but this
was difficult to maintain, and did not allow advanced filters. The
:command:`rootwrap` command replaces :command:`sudo` for Compute.

To use rootwrap, prefix the Compute command with :command:`nova-rootwrap`. For
example:

..  code:: console

    $ sudo nova-rootwrap /etc/nova/rootwrap.conf command

A generic ``sudoers`` entry lets the Compute user run :command:`nova-rootwrap`
as root. The :command:`nova-rootwrap` 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.

..  note::

    Be aware of issues with using NFS and root-owned files. The NFS
    share must be configured with the ``no_root_squash`` option enabled,
    in order for rootwrap to work correctly.

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 imports the Python
modules it needs from a cleaned, system-default PYTHONPATH.
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` executable.

Rootwrap is configured using the :file:`rootwrap.conf` 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 :file:`nova.conf` configuration file
with the ``rootwrap_config=entry`` parameter.

The :file:`rootwrap.conf` file uses an INI file format with these
sections and parameters:

.. list-table:: **rootwrap.conf configuration options**
   :widths: 64 31

   * - Configuration option=Default value
     - (Type) Description
   * - [DEFAULT]
       filters\_path=/etc/nova/rootwrap.d,/usr/share/nova/rootwrap
     - (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.

If the root wrapper is not performing correctly, you can add a
workaround option into the :file:`nova.conf` configuration file. This
workaround re-configures the root wrapper configuration to fall back to
running commands as sudo, and is a Kilo release feature.

Including this workaround in your configuration file safeguards your
environment from issues that can impair root wrapper performance. Tool
changes that have impacted
`Python Build Reasonableness (PBR) <https://git.openstack.org/cgit/openstack-dev/pbr/>`__
for example, are a known issue that affects root wrapper performance.

To set up this workaround, configure the ``disable_rootwrap`` option in
the ``[workaround]`` section of the :file:`nova.conf` configuration file.

The filters definition files contain lists of filters that rootwrap 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 :file:`rootwrap.conf` file.

Filter definition files use an INI file format with a ``[Filters]``
section and several lines, each with a unique parameter name, which
should be different for each filter you define:

.. list-table:: **Filters configuration options**
   :widths: 72 39


   * - Configuration option=Default value
     - (Type) Description
   * - [Filters]
       filter\_name=kpartx: CommandFilter, /sbin/kpartx, root
     - (ListOpt) Comma-separated list containing the filter class to
       use, followed by the Filter arguments (which vary depending
       on the Filter class selected).