#!/usr/bin/perl -w -T

use strict;
use PVE::SafeSyslog;
use PVE::INotify;
use PVE::RPCEnvironment;
use PVE::CLIHandler;
use PVE::API2::VZDump;

use Data::Dumper; # fixme: remove

use base qw(PVE::CLIHandler);

$ENV{'PATH'} = '/sbin:/bin:/usr/sbin:/usr/bin';

initlog('vzdump');

die "please run as root\n" if $> != 0;

PVE::INotify::inotify_init();

my $rpcenv = PVE::RPCEnvironment->init('cli');

$rpcenv->init_request();
$rpcenv->set_language($ENV{LANG});
$rpcenv->set_user('root@pam'); 


my $cmddef = [ 'PVE::API2::VZDump', 'vzdump', 'vmid', undef, 
	       sub {
		   my $upid = shift;
		   my $status = PVE::Tools::upid_read_status($upid);
		   exit($status eq 'OK' ? 0 : -1);
	       }];

push @ARGV, 'help' if !scalar(@ARGV);

PVE::CLIHandler::handle_simple_cmd($cmddef, \@ARGV, undef, $0);

exit 0;

__END__

=head1 NAME

vzdump - backup utility for virtual machine

=head1 SYNOPSIS

=include synopsis

=head1 DESCRIPTION

vzdump is an utility to make consistent snapshots of running virtual
machines (VMs). It basically creates a tar archive of the VM private area,
which also includes the VM configuration files. vzdump currently
supports OpenVZ and QemuServer VMs.

There are several ways to provide consistency (option C<mode>):

=over 2

=item C<stop> mode

Stop the VM during backup. This results in a very long downtime.

=item C<suspend> mode

For OpenVZ, this mode uses rsync to copy the VM to a temporary
location (see option --tmpdir). Then the VM is suspended and a second
rsync copies changed files. After that, the VM is started (resume)
again. This results in a minimal downtime, but needs additional space
to hold the VM copy.

For QemuServer, this mode work like C<stop> mode, but uses
suspend/resume instead of stop/start.

=item C<snapshot> mode

This mode uses LVM2 snapshots. There is no downtime, but snapshot mode
needs LVM2 and some free space on the corresponding volume group to
create the LVM snapshot.

=back 

=head1 BACKUP FILE NAMES

Newer version of vzdump encodes the virtual machine type and the
backup time into the filename, for example

 vzdump-openvz-105-2009_10_09-11_04_43.tar

That way it is possible to store several backup into the same
directory. The parameter C<maxfiles> can be used to specify the maximal
number of backups to keep.

=head1 RESTORE

The resulting tar files can be restored with the following programs.

=over 1

=item vzrestore: OpenVZ restore utility

=item qmrestore: QemuServer restore utility

=back

For details see the corresponding manual pages.

=head1 CONFIGURATION

Global configuration is stored in /etc/vzdump.conf. 

 tmpdir: DIR
 dumpdir: DIR
 storage: STORAGE_ID
 mode: snapshot|suspend|stop
 bwlimit: KBPS
 ionize: PRI
 lockwait: MINUTES 
 stopwait: MINUTES 
 size: MB
 maxfiles: N
 script: FILENAME
 exclude-path: PATHLIST

=head1 HOOK SCRIPT

You can specify a hook script with option C<--script>. This script is called at various phases of the backup process, with parameters accordingly set. You can find an example in the documentation directory (C<vzdump-hook-script.pl>). 

=head1 EXCLUSIONS (OpenVZ only)

vzdump skips the following files wit option --stdexcludes

 /var/log/.+
 /tmp/.+
 /var/tmp/.+
 /var/run/.+pid

You can manually specify exclude paths, for example:

 # vzdump 777 --exclude-path C</tmp/.+> --exclude-path C</var/tmp/.+>

(only excludes tmp directories)

Configuration files are also stored inside the backup archive (/etc/vzdump), and will be correctly restored.

=head1 LIMITATIONS

VZDump does not save ACLs.

=head1 EXAMPLES

Simply dump VM 777 - no snapshot, just archive the VM private area and configuration files to the default dump directory (usually /vz/dump/).

 # vzdump 777

Use rsync and suspend/resume to create an snapshot (minimal downtime).

 # vzdump 777 --mode suspend

Backup all VMs and send notification mails to root and admin.

 # vzdump --all --mode suspend --mailto root --mailto admin

Use LVM2 to create snapshots (no downtime).

 # vzdump 777 --dumpdir /mnt/backup --mode snapshot

Backup more than one VM (selectively)

 # vzdump 101 102 103 --mailto root

Backup all VMs excluding VM 101 and 102

 # vzdump --mode suspend --exclude 101,102

Restore an OpenVZ machine to VM 600

 # vzrestore /mnt/backup/vzdump-openvz-777.tar 600

Restore an Qemu/KVM machine to VM 601

 # qmrestore /mnt/backup/vzdump-qemu-888.tar 601

Clone an existing container 101 to container 300 using pipes

 # vzdump 101 --stdout|vzrestore - 300

=head1 SEE ALSO

vzrestore(1) qmrestore(1)

=include pve_copyright