openstack-manuals/doc/admin-guide-cloud/section_rootwrap.xml

<?xml version="1.0" encoding="UTF-8"?>
<section xml:id="root-wrap-reference"
    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">
    <title>Secure with root wrappers</title>
    <para>The goal of the root wrapper is to allow the nova
        unprivileged user to run a number of actions as the root user,
        in the safest manner possible. Historically, Nova used a
        specific sudoers file listing every command that the nova user
        was allowed to run, and just used sudo to run that command as
        root. However this was difficult to maintain (the sudoers file
        was in packaging), and did not allow for complex filtering of
        parameters (advanced filters). The rootwrap was designed to
        solve those issues.</para>
   <simplesect> <title>How rootwrap works</title>
    <para>Instead of just calling sudo make me a sandwich, Compute services starting with nova- call
        sudo nova-rootwrap /etc/nova/rootwrap.conf make me a sandwich.
        A generic sudoers entry lets the nova user run nova-rootwrap
        as root. The nova-rootwrap 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></simplesect>
    <simplesect>
        <title>Security model</title>
        <para>The escalation path is fully controlled by the root
            user. A sudoers entry (owned by root) allows nova to run
            (as root) a specific rootwrap executable, and only with a
            specific configuration file (which should be owned by
            root). nova-rootwrap imports the Python modules it needs
            from a cleaned (and system-default) PYTHONPATH. 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 nova
            user itself is not in control of the configuration or
            modules used by the nova-rootwrap executable.</para>
    </simplesect>
    <simplesect>
<title>Details of rootwrap.conf</title>
        <para>The <filename>rootwrap.conf</filename> file is used to
            influence how nova-rootwrap works. Since it's in the
            trusted security path, it needs to be owned and writable
            only by the root user. Its location is specified both in
            the sudoers entry and in the
                <filename>nova.conf</filename> configuration file with
            the rootwrap_config= entry.</para>
<para>It uses an INI file format with the following sections and parameters:</para>
        <table rules= "all" frame= "border" xml:id= "rootwrap-conf-table-filter-path" width= "100%">
            <caption>Description of 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
            nova-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 rootwrap.conf file.</para>
        <para>It uses an INI file format with a [Filters] section and several lines, each with a unique parameter name (different for each filter you define):</para>

        <table rules= "all" frame= "border" xml:id= "rootwrap-conf-table-filter-name" width= "100%">
            <caption>Description of 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>
                    [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>