Bug 1821012

Summary:	[Documentation] - In the administration guide of RHEV4.4 the command of execution of restoring a complete backup or a database backup isn't up to date
Product:	Red Hat Enterprise Virtualization Manager	Reporter:	Shir Fishbain <sfishbai>
Component:	Documentation	Assignee:	Eli Marcus <emarcus>
Status:	CLOSED CURRENTRELEASE	QA Contact:	rhev-docs <rhev-docs>
Severity:	medium	Docs Contact:
Priority:	medium
Version:	4.4.0	CC:	didi, emarcus
Target Milestone:	ovirt-4.5.3-async	Keywords:	Documentation
Target Release:	4.5.2
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:	docscope 4.5
Fixed In Version:		Doc Type:	If docs needed, set a value
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2023-05-16 14:23:00 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	Infra	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Shir Fishbain 2020-04-05 12:18:47 UTC

Description of problem:
In the administration guide of RHEV4.4 the execution of restoring a complete backup or a database backup isn't up to date for 4.4V.
When execute retoring before running engine-setup as in the doc:

# engine-backup --mode=restore --file=file_name --log=log_file_name --provision-db --restore-permissions

received: FATAL: Can't connect to database 'ovirt_engine_history'. 
Please see '/usr/bin/engine-backup --help'.

Version-Release number of selected component (if applicable):
engine - ovirt-engine-4.4.0-0.29.master.el8ev.noarch

Actual results:
The restore in the doc performe with --provision-db:

storage-ge-09 ~]# engine-backup --mode=restore --file=/root/cinderlib_from_old_engine --log=/root/log_cinderlib_from_old_engine --provision-db --restore-permissions
Start of engine-backup with mode 'restore'
scope: all
archive file: /root/cinderlib_from_old_engine
log file: /root/log_cinderlib_from_old_engine
Preparing to restore:
- Unpacking file '/root/cinderlib_from_old_engine'
Restoring:
- Files
Provisioning PostgreSQL users/databases:
- user 'engine', database 'engine'
Restoring:
FATAL: Can't connect to database 'ovirt_engine_history'. Please see '/usr/bin/engine-backup --help'.

Expected results:
The restore should be performe in the doc with --provision of all databases :

storage-ge-09 ~]# engine-backup --mode=restore --file=/root/cinderlib_from_old_engine --log=/root/log_cinderlib_from_old_engine --provision-all-databases --restore-permissions

Start of engine-backup with mode 'restore'
scope: all
archive file: /root/cinderlib_from_old_engine
log file: /root/log_cinderlib_from_old_engine
Preparing to restore:
- Unpacking file '/root/cinderlib_from_old_engine'
Restoring:
- Files
Provisioning PostgreSQL users/databases:
- user 'engine', database 'engine'
- user 'ovirt_engine_history', database 'ovirt_engine_history'
- user 'ovirt_cinderlib', database 'ovirt_cinderlib'
Restoring:
- Engine database 'engine'
  - Cleaning up temporary tables in engine database 'engine'
  - Updating DbJustRestored VdcOption in engine database
  - Resetting DwhCurrentlyRunning in dwh_history_timekeeping in engine database
  - Resetting HA VM status
------------------------------------------------------------------------------
Please note:

The engine database was backed up at 2020-03-29 17:27:48.000000000 +0300.

Objects that were added, removed or changed after this date, such as virtual
machines, disks, etc., are missing in the engine, and will probably require
recovery or recreation.
------------------------------------------------------------------------------
- DWH database 'ovirt_engine_history'
- Cinderlib database 'ovirt_cinderlib'
You should now run engine-setup.
Done.

Comment 1 Nikolai Sednev 2020-04-05 14:06:43 UTC

Cinderlib commands are not covered in 4.4 documentation for backup and restore.

Comment 2 Martin Perina 2020-04-16 07:54:19 UTC

I don't understand the scenario. Are you trying to restore only cinderlib database? Or are you trying to restore complete backup (which include engine, DWH and cinderlib database)?

Comment 3 Nikolai Sednev 2020-04-16 08:47:36 UTC

(In reply to Martin Perina from comment #2)
> I don't understand the scenario. Are you trying to restore only cinderlib
> database? Or are you trying to restore complete backup (which include
> engine, DWH and cinderlib database)?

Documentation is missing all types of Cinderlib db backup and restore options, there are new commands which not covered for the new functionality.
We did full backup and restore, including all types also with DWH.
Backup was like: “engine-backup --scope=all --mode=backup --file=cinderlib_from_old_engine --log=log_cinderlib_from_old_engine”.
Restore was like: "engine-backup --mode=restore --file=/root/cinderlib_from_old_engine --log=/root/log_cinderlib_from_old_engine --provision-all-databases --restore-permissions".

Comment 4 Martin Perina 2020-04-16 09:50:23 UTC

OK, moving to downstream bug and assigning to documentation team

Comment 5 Yedidyah Bar David 2020-05-06 13:06:44 UTC

Copying parts of bug 1707225 comment 28:

The minimum, as of 4.3 (bug 1530031), is:

Backup:

# engine-backup

Restore:

# engine-backup --mode=restore --file=backupfile --provision-all-databases

Notably:

- scope defaults to all (since several versions ago)

- mode defaults to backup

- file, in backup mode, defaults to a file in /var/lib/ovirt-engine-backup/

- log defaults to a file in /var/log/ovirt-engine-backup/

- If restoring, and passing any --provision* option, we default to --restore-permissions

We should find and replace all occurrences of calls to engine-backup across all the documentation with one of the above (backup or restore), with the only exception being the specific documentation for engine-backup itself.

Comment 9 Eli Marcus 2023-04-03 15:51:28 UTC

(In reply to Yedidyah Bar David from comment #5)
> Copying parts of bug 1707225 comment 28:
> 
> The minimum, as of 4.3 (bug 1530031), is:
> 
> Backup:
> 
> # engine-backup
> 
> Restore:
> 
> # engine-backup --mode=restore --file=backupfile --provision-all-databases
> 
> Notably:
> 
> - scope defaults to all (since several versions ago)
> 
> - mode defaults to backup
> 
> - file, in backup mode, defaults to a file in /var/lib/ovirt-engine-backup/
> 
> - log defaults to a file in /var/log/ovirt-engine-backup/
> 
> - If restoring, and passing any --provision* option, we default to
> --restore-permissions
> 
> We should find and replace all occurrences of calls to engine-backup across
> all the documentation with one of the above (backup or restore), with the
> only exception being the specific documentation for engine-backup itself.
Hi Didi - 
here is the draft PR for the updates - https://github.com/oVirt/ovirt-site/pull/3142

https://ovirt.github.io/ovirt-site/previews/3142/documentation/administration_guide/index.html#sect-Backing_Up_and_Restoring_the_Red_Hat_Enterprise_Virtualization_Manager

- I see that the online help in the engine-backup command is very old - should I remove all the references in the docs to "see engine-backup --help"?
- I have added default descriptions to the "basic options" and the "Creating a backup with the engine-backup command" sections in the Administration guide
- Should I also modify the restore chapters to remove the default options from the commands?

Comment 10 Yedidyah Bar David 2023-04-04 06:31:00 UTC

(In reply to Eli Marcus from comment #9)
> (In reply to Yedidyah Bar David from comment #5)
> > Copying parts of bug 1707225 comment 28:
> > 
> > The minimum, as of 4.3 (bug 1530031), is:
> > 
> > Backup:
> > 
> > # engine-backup
> > 
> > Restore:
> > 
> > # engine-backup --mode=restore --file=backupfile --provision-all-databases
> > 
> > Notably:
> > 
> > - scope defaults to all (since several versions ago)
> > 
> > - mode defaults to backup
> > 
> > - file, in backup mode, defaults to a file in /var/lib/ovirt-engine-backup/
> > 
> > - log defaults to a file in /var/log/ovirt-engine-backup/
> > 
> > - If restoring, and passing any --provision* option, we default to
> > --restore-permissions
> > 
> > We should find and replace all occurrences of calls to engine-backup across
> > all the documentation with one of the above (backup or restore), with the
> > only exception being the specific documentation for engine-backup itself.
> Hi Didi - 
> here is the draft PR for the updates -
> https://github.com/oVirt/ovirt-site/pull/3142

Reviewed.

> 
> https://ovirt.github.io/ovirt-site/previews/3142/documentation/
> administration_guide/index.html#sect-
> Backing_Up_and_Restoring_the_Red_Hat_Enterprise_Virtualization_Manager
> 
> - I see that the online help in the engine-backup command is very old -

Where do you see this? We did update it when changing functionality of the
command. Might have missed something.

> should I remove all the references in the docs to "see engine-backup --help"?

I don't think so.

We also kept updating the man page (`man engine-backup`), although less
strictly than `--help`.

> - I have added default descriptions to the "basic options" and the "Creating
> a backup with the engine-backup command" sections in the Administration guide
> - Should I also modify the restore chapters to remove the default options
> from the commands?

I think so, yes. Thanks!

Comment 11 Eli Marcus 2023-05-16 14:23:00 UTC

PR finalized and merged