From 23d4e0e9c07f1ff6646e2f6236ee9625abd2a5cb Mon Sep 17 00:00:00 2001 From: Brian Rosmaita Date: Thu, 5 Jul 2018 16:51:37 -0400 Subject: [PATCH] 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 --- doc/source/admin/db.rst | 93 +++++++++++++++++++ ...p-mitigate-ossn-0075-c0e74e60d86d8ea2.yaml | 12 +++ 2 files changed, 105 insertions(+) create mode 100644 releasenotes/notes/bp-mitigate-ossn-0075-c0e74e60d86d8ea2.yaml diff --git a/doc/source/admin/db.rst b/doc/source/admin/db.rst index 59dcfeef4a..85334ef953 100644 --- a/doc/source/admin/db.rst +++ b/doc/source/admin/db.rst @@ -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 + `_, "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 + `_ + 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 `_ 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 +`_ 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. diff --git a/releasenotes/notes/bp-mitigate-ossn-0075-c0e74e60d86d8ea2.yaml b/releasenotes/notes/bp-mitigate-ossn-0075-c0e74e60d86d8ea2.yaml new file mode 100644 index 0000000000..e368362d88 --- /dev/null +++ b/releasenotes/notes/bp-mitigate-ossn-0075-c0e74e60d86d8ea2.yaml @@ -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