Documentation for OSSN-0075 mitigation

Updates the Glance Administration Guide and adds a release note.

Depends-on: https://review.openstack.org/#/c/579507/
Change-Id: I87343b67614da8dea3a09b10456f4bfc0042ed0e
This commit is contained in:
Brian Rosmaita 2018-07-05 16:51:37 -04:00
parent d01c004ccc
commit 23d4e0e9c0
2 changed files with 105 additions and 0 deletions

View File

@ -16,6 +16,9 @@
Database Management
===================
Updating and Migrating the Database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The default metadata driver for Glance uses `SQLAlchemy`_, which implies there
exists a backend database which must be managed. The ``glance-manage`` binary
provides a set of commands for making this easier.
@ -128,3 +131,93 @@ upgrade, you should make a full database backup of your production data. As of
the OpenStack Kilo release (April 2013), database downgrades are not supported,
and the only method available to get back to a prior database version is to
restore from backup.
Database Maintenance
~~~~~~~~~~~~~~~~~~~~
Like most OpenStack systems, Glance performs *soft* deletions when it deletes
records from its database. Depending on usage patterns in your cloud, you may
occasionally want to actually remove such soft deleted table rows. This
operation is called *purging* the database, and you can use the
``glance-manage`` tool to do this.
High-Level Database Architecture
--------------------------------
Roughly, what we've got in the glance database is an **images** table that
stores the image **id** and some other core image properties. All the other
information about the image (for example: where the image data is stored in
the backend, what projects an image has been shared with, image tags, custom
image properties) is stored in other tables in which the **image id** is
a foreign key.
Because the **images** table keeps track of what image identifiers have been
issued, it must be treated differently from the other tables with respect to
purging the database.
.. note::
Before the Rocky release (17.0.0), the **images** table was *not* treated
differently, which made Glance vulnerable to `OSSN-0075
<https://wiki.openstack.org/wiki/OSSN/OSSN-0075>`_, "Deleted Glance image
IDs may be reassigned". Please read through that OpenStack Security
Note to understand the nature of the problem.
Additionally, the Glance spec `Mitigate OSSN-0075
<https://specs.openstack.org/openstack/glance-specs/specs/rocky/approved/glance/mitigate-ossn-0075.html>`_
contains a discussion of the issue and explains the changes made to the
``glance-manage`` tool for the Rocky release. The `Gerrit review of the
spec <https://review.openstack.org/468179>`_ contains an extensive
discussion of several alternative approaches and will give you an idea of
why the Glance team provided a "mitigation" instead of a fix.
Purging the Database
--------------------
You can use the ``glance-manage`` tool to purge the soft-deleted rows from
all tables *except* the images table::
glance-manage db purge
This command takes two optional parameters:
--age_in_days NUM Only purge rows that have been deleted for longer
than *NUM* days. The default is 30 days.
--max_rows NUM Purge a maximum of *NUM* rows from each table.
The default is 100.
Purging the Images Table
------------------------
Remember that image identifiers are used by other OpenStack services that
require access to images. These services expect that when an image is
requested by ID, they will receive the same data every time. When the
**images** table is purged of its soft-deleted rows, Glance loses its
memory that those image IDs were ever mapped to some particular payload.
Thus, care must be taken in purging the **images** table. We recommend
that it be done much less frequently than the "regular" purge operation.
Use the following command to purge the images table::
glance-manage db purge_images_table
Be sure you have read and understood the implications of `OSSN-0075
<https://wiki.openstack.org/wiki/OSSN/OSSN-0075>`_ before you use this
command, which purges the soft-deleted rows from the images table.
It takes two optional parameters:
--age_in_days NUM Only purge rows that have been deleted for longer
than *NUM* days. The default is 180 days.
--max_rows NUM Purge a maximum of *NUM* rows from the **images** table.
The default is 100.
It is possible for this command to fail with an IntegrityError saying
something like "Cannot delete or update a parent row: a foreign key
constraint fails". This can happen when you try to purge records from
the **images** table when related records have not yet been purged from
other tables. The ``purge_images_table`` command should only be issued
after all related information has been purged using the "regular" ``purge``
command.

View File

@ -0,0 +1,12 @@
---
prelude: >
- The ``glance-manage`` utility has been updated to address OpenStack
Security Note OSSN-0075.
security:
- |
The ``glance-manage`` tool has been updated to address `OSSN-0075`_.
Please see the `Database Maintenance`_ section of the Glance
Administration Guide for details.
.. _`OSSN-0075`: https://wiki.openstack.org/wiki/OSSN/OSSN-0075
.. _`Database Maintenance`: https://docs.openstack.org/glance/latest/admin/db.html#database-maintenance