Bug 1208114

Summary:	RHEVM Postgres Update docs & man page
Product:	Red Hat Enterprise Virtualization Manager	Reporter:	Chris Reynolds <creynold>
Component:	Documentation	Assignee:	Lucy Bopf <lbopf>
Status:	CLOSED CURRENTRELEASE	QA Contact:	Tahlia Richardson <trichard>
Severity:	medium	Docs Contact:
Priority:	medium
Version:	3.4.0	CC:	adahms, creynold, didi, ecohen, gklein, jpullen, lbopf, lsurette, pstehlik, rbalakri, thildred, yeylon
Target Milestone:	---
Target Release:	---
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:		Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2015-05-20 05:46:22 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:
Bug Depends On:
Bug Blocks:	1220637

Description Chris Reynolds 2015-04-01 12:37:31 UTC

Description of problem:

From SFDC 01358685:

The 3.4 documents and man page on engine-backup lists only two types of backups. Those are '--all' and '--db'. When we tried doing a standard '--all' backup, we had lots of filesystem errors, and were capturing the report data that we didn't necessarily need to recover anyways. So we tried the '--db' mode of recovery and ran into the issue that eventually became this bug.

In going through the process of troubleshooting this and the case owner explained that the '--files' scope must be included when doing a '--db' backup. This scope is not mentioned in the 3.4 docs or man page, although the flag is listed in the '--help'. I retested the process and this did work. I think there are other situations where doing a limited backup may be a desired feature, and the process needs to be documented. A better bug would be updating the docs and man page for engine-backup to include the correct procedure for performing the smallest backup necessary to recover access to the engine. Or said differently, how to perform a limited backup that excludes data such as reports and statistics, and the process for restoring that limited backup.

Version-Release number of selected component (if applicable):
3.4

How reproducible:
Very

Steps to Reproduce:
1. Open RH Docs or Man page

Actual results:
Docs missing argument or instructions are not clear.

Expected results:
Inclusion of flags

Additional info:

Comment 1 Jeff Pullen 2015-04-01 14:27:59 UTC

Clarification:
The title of this bug is misleading. This is actually for the engine-backup man pages and the RHEV 3.4 Administration Guide (Chapter 15 Backing up and Restoring the Red Hat Enterprise Virtualization Manager).

Problem:
Running a 'engine-backup --help' list multiple backup scopes that are not mentioned in the Administration guide, or in the man pages. The only two scopes mentioned in our docs are 'all' and 'db'. There is no mention that performing a 'db' scope backup also requires a 'files' scope backup, or a filesystem copy to restore.

Business case:
Customers reading our documentation may believe they are protected with a 'db' only backup, but will be unable to return to a working configuration. In Example 15.2. "Creating an engine database Backup", it is even demonstrated as an alternative to the default without any mention of the additional requirements.

Proposed fixes:
1) The man pages for engine-backup should be updated to match the features and functionality of the tool.

2) The Administration Guide should be updated to match the features and functionality of the tool.

3) Both should provide a clear warning that a db only backup is insufficient to restore to a fresh installation of RHEVM. 

4) Examples of a db only backup should include a backup using the 'files' scope, as both are required in the case of disaster recovery.

Comment 13 Andrew Dahms 2015-05-12 22:46:59 UTC

Moving to Sprint 6 tracker.