----- On Sep 16, 2017, at 12:41 AM, jsnow [email protected] wrote:
> On 09/08/2017 12:41 PM, Ishani Chugh wrote: >> qemu-backup will be a command-line tool for performing full and >> incremental disk backups on running VMs. It is intended as a >> reference implementation for management stack and backup developers >> to see QEMU's backup features in action. This commit is an >> initial implementation of manpage listing the commands which the >> backup tool will support. The manpage will be built along with other >> docs when configure is provided with --enable-docs flag in the >> location contrib/backup in build directory. >> >> Signed-off-by: Ishani Chugh <[email protected]> >> --- >> Makefile | 14 ++-- >> contrib/backup/qemu-backup.texi | 142 >> ++++++++++++++++++++++++++++++++++++++++ >> 2 files changed, 152 insertions(+), 4 deletions(-) >> create mode 100644 contrib/backup/qemu-backup.texi >> >> diff --git a/Makefile b/Makefile >> index 337a1f6..794cac5 100644 >> --- a/Makefile >> +++ b/Makefile >> @@ -209,6 +209,7 @@ ifdef BUILD_DOCS >> DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 qemu-ga.8 >> DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt >> docs/interop/qemu-qmp-ref.7 >> DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt >> docs/interop/qemu-ga-ref.7 >> +DOCS+=contrib/backup/qemu-backup.html contrib/backup/qemu-backup.txt >> ifdef CONFIG_VIRTFS >> DOCS+=fsdev/virtfs-proxy-helper.1 >> endif >> @@ -517,6 +518,8 @@ VERSION ?= $(shell cat VERSION) >> >> dist: qemu-$(VERSION).tar.bz2 >> >> +qemu-backup.8: contrib/backup/qemu-backup.texi >> + >> qemu-%.tar.bz2: >> $(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst >> qemu-%.tar.bz2,%,$@)" >> >> @@ -728,16 +731,19 @@ fsdev/virtfs-proxy-helper.1: >> fsdev/virtfs-proxy-helper.texi >> qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi >> qemu-ga.8: qemu-ga.texi >> >> -html: qemu-doc.html docs/interop/qemu-qmp-ref.html >> docs/interop/qemu-ga-ref.html >> -info: qemu-doc.info docs/interop/qemu-qmp-ref.info >> docs/interop/qemu-ga-ref.info >> -pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf >> -txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt >> +html: qemu-doc.html docs/interop/qemu-qmp-ref.html >> docs/interop/qemu-ga-ref.html contrib/backup/qemu-backup.html >> +info: qemu-doc.info docs/interop/qemu-qmp-ref.info >> docs/interop/qemu-ga-ref.info contrib/backup/qemu-backup.info >> +pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf >> contrib/backup/qemu-backup.pdf >> +txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt >> contrib/backup/qemu-backup.txt >> >> qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \ >> qemu-img.texi qemu-nbd.texi qemu-options.texi qemu-option-trace.texi \ >> qemu-monitor.texi qemu-img-cmds.texi qemu-ga.texi \ >> qemu-monitor-info.texi >> >> +contrib/backup/qemu-backup.html contrib/backup/qemu-backup.pdf >> contrib/backup/qemu-backup.txt contrib/backup/qemu-backup.info: \ >> + contrib/backup/qemu-backup.texi >> + >> docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \ >> docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \ >> docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7: \ >> diff --git a/contrib/backup/qemu-backup.texi >> b/contrib/backup/qemu-backup.texi >> new file mode 100644 >> index 0000000..7ad266c >> --- /dev/null >> +++ b/contrib/backup/qemu-backup.texi >> @@ -0,0 +1,142 @@ >> +\input texinfo >> +@setfilename qemu-backup >> + >> +@documentlanguage en >> +@documentencoding UTF-8 >> + >> +@settitle QEMU Backup Tool >> +@copying >> + >> +Copyright @copyright{} 2017 The QEMU Project developers >> +@end copying >> +@ifinfo >> +@direntry >> +* QEMU: (QEMU-backup). Man page for QEMU Backup Tool. >> +@end direntry >> +@end ifinfo >> +@iftex >> +@titlepage >> +@sp 7 >> +@center @titlefont{QEMU Backup Tool} >> +@sp 1 >> +@sp 3 >> +@end titlepage >> +@end iftex >> +@ifnottex >> +@node Top >> +@top Short Sample >> + >> +@menu >> +* Name:: >> +* Synopsis:: >> +* List of Commands:: >> +* Command Parameters:: >> +* Command Descriptions:: >> +* License:: >> +@end menu >> + >> +@end ifnottex >> + >> +@node Name >> +@chapter Name >> + >> +QEMU disk backup tool. >> + >> +@node Synopsis >> +@chapter Synopsis >> + >> +qemu-backup command [command options]. >> + >> +@node List of Commands >> +@chapter List of Commands >> +@itemize >> +@item qemu-backup guest add --guest guestname --qmp socketpath >> +@item qemu-backup guest list >> +@item qemu-backup drive add --id driveid --guest guestname --target target >> +@item qemu-backup drive add --all --guest guestname --target target >> +@item qemu-backup drive list --guest guestname >> +@item qemu-backup restore --guest guestname >> +@item qemu-backup guest remove --guest guestname >> +@item qemu-backup drive remove --guest guestname --id driveid >> +@end itemize >> +@node Command Parameters >> +@chapter Command Parameters >> +@itemize >> +@item --all: Add all the drives present in a guest which are suitable for >> backup. >> +@item --guest: Name of the guest. >> +@item --id: id of guest or drive. >> +@item --qmp: Path of qmp socket. >> +@item --target: Destination path on which you want your backup to be made. >> +@end itemize >> + >> +@node Command Descriptions >> +@chapter Command Descriptions >> +@itemize >> +@item qemu-backup guest add --guest guestname --qmp socketpath >> +This command adds a guest to the configuration file given its path to qmp >> socket. > > In the generated output (contrib/backup/qemu-backup.html) this doesn't > actually create a newline, and the resultant text looks like this: > > qemu-backup guest add –guest guestname –qmp socketpath This command adds > a guest to the configuration file given its path to qmp socket. > > Looking at some other texi docs, @item appears by itself on a newline: > > (from qemu-doc.texi:) > > @item > QEMU can optionally use an in-kernel accelerator, like kvm. The > accelerators > execute most of the guest code natively, while > continuing to emulate the rest of the machine. > > If your intention was to create a heading and a paragraph, you may need > additional markup to accomplish this. The resulting documentation is a > little difficult to read otherwise. > >> + >> +example: > > Perhaps "examples" as there are two that follow. > >> +qemu-backup guest add --id=fedora --qmp=unix:/var/run/qemu/fedora.sock >> + >> +qemu-backup guest add --id=fedora --qmp=tcp:localhost:4444 >> + >> +@item qemu-backup guest list >> +This commands lists the names of guests which are added to configuration >> file. > > "to the configuration file" > >> + >> +@item qemu-backup drive add --guest guestname --id driveid --target target >> +This command adds different drives for backup in a particular guest by >> giving >> the name of drive to be backed up and target imagefile in which we want to >> store the drive backup. > > "of the drive", > "and a target image file where the drive backup is to be stored." > >> + >> +example: qemu-backup drive add --guest=fedora --id=root >> --target=/backup/root.img >> + >> +@item qemu-backup drive add --all --guest guestname --destination >> destination >> +This command adds all the drives of the guest for backup other than CDROM >> drive >> and read-only drives. Here all the backup drives will have the same names as >> original drives and target will be the destination folder. >> + >> +example: qemu-backup drive add --all --guest fedora --destination >> =/backup/fedora/ >> + > > extra space between destination and =/backup/fedora > >> +@item qemu-backup drive list --guest guestname >> +This commands gives the names of the drive present in a guest which are >> added >> for backup. >> + > > "of the drives", and perhaps "which have been configured for backup" > >> +example: qemu-backup drive list --guest=fedora >> + >> +@item qemu-backup backup --guest guestname >> + >> +This command makes the backup of the drives, in their respective given >> destinations. The ids of drive and their destinations are taken from the >> configuration file. >> + >> +example: qemu-backup backup --guest=fedora >> + >> +@item qemu-backup restore --guest guestname >> +This command is needed if we want to restore the backup. It will list the >> commands to be run for performing the same but will not perform any action. >> + > > Might be worthwhile to explain why it won't automatically perform these > actions for you, i.e. any one of these reasons: > > - To allow you to safely shut down your VM to preserve data integrity > for drives that are (perhaps) not being restored > - To allow the administrator a chance to move backups that were moved > off-site back onto the server > - To allow the administrator a chance to move backups in a more > efficient way if possible/desired (a python utility may not always have > the best information for how to do an efficient restoration, for > instance...) > >> +example: qemu-backup restore --guest=fedora >> + >> +@item qemu-backup guest remove --guest guestname >> +This command removes the guest from the configuration file. >> + >> +example: qemu-backup guest remove --guest=fedora >> + >> +@item qemu-backup drive remove --guest guestname --id driveid >> +This command helps remove a drive which is set for backup in configuration >> of >> given host. >> + > > "helps remove" should just be "removes" > >> +example: drive remove --guest=fedora --id=root >> + >> +@item A full backup can be performed by following the given steps: >> + >> +Perform a full backup of 'vm001', which has one drive: >> + >> +qemu-backup guest add --guest vm001 --qmp /path/to/vm001.sock >> + >> +qemu-backup add --id drive0 --guest vm001 --target /backups/vm001-drive0.img >> + >> +qemu-backup backup --guest vm001 >> + >> + >> +@end itemize >> + >> +@node License >> +@appendix License >> +QEMU is a trademark of Fabrice Bellard. >> +QEMU is released under the >> +@url{https://www.gnu.org/licenses/gpl-2.0.txt,GNU General Public License}, >> +version 2. Parts of QEMU have specific licenses, see file >> +@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE,LICENSE}. >> +@bye >> -- >> 2.7.4 >> > > Looks good so far, thank you for your work this summer :) > > Since Stefan gave his Reviewed-by for the whole series, I'll leave it up > to you as to whether or not you want to continue sending revisions. If > you'd like to move on and work on something else, I can always send some > fixup patches myself. > > Let me know! > > In the event that you'd like to press on: > > Reviewed-by: John Snow <[email protected]> Thanks for review. I will address the comments in next revision. I would like to keep on contributing and sending revisions. Thanks for being so helpful entire summer :) Regards, Ishani
