Merge lp:~percona-dev/percona-xtrabackup/innobackupex-docs into lp:percona-xtrabackup/2.0

[Alexey Kopytov]

[Vadim Tkachenko (vadim-tk)]

good for me

review: Approve

=== modified file 'innobackupex'
--- innobackupex	2011-03-05 08:12:55 +0000
+++ innobackupex	2011-03-25 04:55:20 +0000
@@ -3,12 +3,13 @@
 # A script for making backups of InnoDB and MyISAM tables, indexes and .frm
 # files.
 #
-# Copyright 2003, 2009 Innobase Oy. All Rights Reserved.
+# Copyright 2003, 2009 Innobase Oy and Percona Inc 2009-2011. All Rights Reserved.
 #
 
 use strict;
 use Getopt::Long;
 use File::Spec;
+use Pod::Usage qw(pod2usage);
 use POSIX "strftime";
 use POSIX ":sys_wait_h";
 use POSIX "tmpnam";
@@ -22,8 +23,8 @@
 
 # copyright notice
 my $copyright_notice = 
-"InnoDB Backup Utility v${innobackup_version}; Copyright 2003, 2009 Innobase Oy.
-All Rights Reserved.
+"InnoDB Backup Utility v${innobackup_version}; Copyright 2003, 2009 Innobase Oy
+and Percona Inc 2009-2011.  All Rights Reserved.
 
 This software is published under
 the GNU GENERAL PUBLIC LICENSE Version 2, June 1991.
@@ -301,236 +302,9 @@
 # usage subroutine prints instructions of how to use this program to stdout.
 #
 sub usage {
-    print STDOUT <<EOF;
-
-Usage:
-$innobackup_script [--sleep=MS] [--compress[=LEVEL]] [--include=REGEXP] [--user=NAME] 
-           [--password=WORD] [--port=PORT] [--socket=SOCKET] [--no-timestamp] 
-           [--ibbackup=IBBACKUP-BINARY] [--slave-info] [--stream=tar]
-           [--scpopt=OPTIONS-FOR-SCP]
-           [--defaults-file=MY.CNF]
-           [--databases=LIST] [--remote-host=HOSTNAME] [--no-lock] BACKUP-ROOT-DIR
-$innobackup_script --apply-log [--use-memory=MB] [--uncompress] [--defaults-file=MY.CNF]
-           [--export] [--redo-only] [--ibbackup=IBBACKUP-BINARY] BACKUP-DIR
-$innobackup_script --copy-back [--defaults-file=MY.CNF] BACKUP-DIR
-
-The first command line above makes a hot backup of a MySQL database.
-By default it creates a backup directory (named by the current date
-and time) in the given backup root directory.  With the --no-timestamp
-option it does not create a time-stamped backup directory, but it puts
-the backup in the given directory (which must not exist).  This
-command makes a complete backup of all MyISAM and InnoDB tables and
-indexes in all databases or in all of the databases specified with the
---databases option.  The created backup contains .frm, .MRG, .MYD,
-.MYI, .TRG, .TRN, .ARM, .ARZ, .CSM, .CSV, .opt, .par, and InnoDB data and log files.
-The MY.CNF options file defines the location of the database.  This command
-connects to the MySQL server using mysql client program, and runs
-ibbackup (InnoDB Hot Backup program) as a child process.
-
-The command with --apply-log option prepares a backup for starting a MySQL
-server on the backup. This command expands InnoDB data files as specified
-in BACKUP-DIR/backup-my.cnf using BACKUP-DIR/ibbackup_logfile,
-and creates new InnoDB log files as specified in BACKUP-DIR/backup-my.cnf.
-The BACKUP-DIR should be a path name of a backup directory created by
-innobackup. This command runs ibbackup as a child process, but it does not 
-connect to the database server. 
-
-The command with --copy-back option copies data, index, and log files
-from backup directory back to their original locations.
-The MY.CNF options file defines the original location of the database.
-The BACKUP-DIR is a path name of a backup directory created by innobackup.
-
-On success the exit code of innobackup process is 0. A non-zero exit code 
-indicates an error.
-
-
-Options:
-    --help      Display this helpscreen and exit.
-
-    --version   Print version information and exit.
-
-    --defaults-file=[MY.CNF]
-                This option is passed to the xtrabackup child process.
-                It specify which file only read default options from.
-
-    --apply-log Prepare a backup for starting mysql server on the backup. 
-                Expand InnoDB data files as specified in 
-                backup-dir/backup-my.cnf, using backup-dir/ibbackup_logfile, 
-                and create new log files as specified in 
-                backup-dir/backup-my.cnf.
-
-    --redo-only Options is used with --apply-log. This option forces to skip
-                "rollback" phase and do only "redo". This is necessary to use
-                if backup later will be applied with incremental changes.
-
-    --copy-back Copy data and index files from backup directory back to 
-                their original locations.
-
-    --remote-host=HOSTNAME
-                If this option is specified, backup files will be created
-                at the remote host by using ssh connection.
-
-    --stream=[tar|cpio(not implemented)]
-                If this option is specified, backup to STDOUT as specified
-                format.  Uses tar4ibd (available in XtraBackup binary).
-
-    --tmpdir=DIRECTORY
-                When --remote-host or --stream specified, transaction log
-                should be stored temporary. The default value is same to
-                mysqld setting.
-
-    --use-memory=MB
-                This option is passed to the ibbackup child process.
-                It tells ibbackup that it can use MB megabytes of 
-                memory in restoration.
-                Try 'ibbackup --help' for more details on this option.
-
-    --parallel=NUMBER-OF-THREADS
-                This option is passed to the xtrabackup child process.
-                It specifies the number of threads used by xtrabackup for
-                parallel data transfer. The default value is 1 (i.e. no
-                parallel copying).
-
-    --throttle=IOS
-                This option is passed to the xtrabackup child process.
-                It limits count of IO operations (pairs of read&write) per
-                second to IOS values (for '--backup')
-
-    --sleep=MS  This option is passed to the ibbackup child process.
-                It instructs the ibbackup program to sleep 
-                MS milliseconds after each 1 MB of copied data.
-                You can use this parameter to tune the additional 
-                disk i/o load the ibbackup program causes on the computer.
-                Try 'ibbackup --help' for more details on this option.
-                ** it is not supported by xtrabackup **
-
-    --compress[=LEVEL]
-                This option is passed to the ibbackup child process.
-                It instructs ibbackup to compress the backup copies of 
-                InnoDB data files. Compression level can be
-                specified as an optional argument. Compression level is 
-                an integer between 0 and 9: 1 gives fastest compression, 
-                9 gives best compression, and 0 means no compression. 
-                If compression level is not given, the default level 1 is used.
-                Try 'ibbackup --help' for more details on this option.
-                ** it is not supported by xtrabackup yet **
-
-    --include=REGEXP 
-                This option is passed to the ibbackup child process.
-                It tells ibbackup to backup only those per-table data
-                files which match the given regular expression.  For
-                each table with a per-table data file a string of the
-                form db_name.table_name is checked against the regular
-                expression.  If the regular expression matches the
-                complete string db_name.table_name, the table is
-                included in the backup. The regular expression should
-                be of the POSIX 1003.2 "extended" form.  
-                Try 'ibbackup --help' for more details on this option.
-
-    --databases=LIST
-                This option is used to specify the list of databases that
-                innobackup should backup. The list is of the form
-                "db_name[.table_name] db_name1[.table_name1] ...".
-                If this option is not specified all databases containing 
-                MyISAM and InnoDB tables will be backed up. 
-                Please make sure that --databases contains all of the 
-                innodb databases & tables so that all of the innodb .frm 
-                files are also backed up. In case the list is very long, 
-                this can be specified in a file and the full path of the 
-                file can be specified instead of the list.
-
-    --tables-file=FILE
-                This option is passed to xtrabackup --tables-file.  It
-                filters the tables to backup by a list of database.table
-                names listed in the given file, one per line.
-
-    --uncompress
-                This option is passed to the ibbackup child process.
-                It tells ibbackup to uncompress compressed InnoDB data files.
-                Try 'ibbackup --help' for more details on this option.
-                ** it is not supported by xtrabackup yet **
-                
-    --export    This option is passed to the xtrabackup child process.
-                It is effective with '--prepare' option.
-                It tells xtrabackup to output "clean" .ibd files and .exp
-                files for 'ALTER TABLE ... IMPORT TABLESPACE' command
-                at innodb_expand_import option enabled XtraDB.
-
-    --user=NAME This option is passed to the mysql child process.
-                It defines the user for database login if not current user.
-                Try 'mysql --help' for more details on this option.
-
-    --password=WORD
-                This option is passed to the mysql child process.
-                It defines the password to use when connecting to database.
-                Try 'mysql --help' for more details on this option.
-
-    --host=HOST This option is passed to the mysql child process.
-                It defines the host to use when connecting to database
-                server with TCP/IP.
-                Try 'mysql --help' for more details on this option.
-
-    --port=PORT This option is passed to the mysql child process.
-                It defines the port to use when connecting to database
-                server with TCP/IP.
-                Try 'mysql --help' for more details on this option.
-
-    --safe-slave-backup
-                Stop slave SQL thread and wait to start backup until
-                Slave_open_temp_tables in SHOW STATUS is zero.  If
-                there are no open temp tables, the backup will take place,
-                else the SQL thread will be started and stopped until there
-                are no open temp tables.  The backup will fail if
-                Slave_open_temp_tables does not become zero after
-                --safe-slave-backup-timeout seconds.  The slave SQL thread
-                will be restarted when the backup finishes.
-
-    --safe-slave-backup-timeout
-                 How many seconds --safe-slave-backup should wait for
-                 Slave_open_temp_tables to become zero.  (default 300)
-
-    --slave-info
-                This option is useful when backing up a replication
-                slave server. It prints the binary log position and
-                name of the binary log file of the master server.
-                It also writes this information to the 'ibbackup_slave_info'
-                file as a 'CHANGE MASTER' command. A new slave for this
-                master can be set up by starting a slave server on this 
-                backup and issuing a 'CHANGE MASTER' command with the binary 
-                log position saved in the 'ibbackup_slave_info' file.
-
-    --socket=SOCKET
-                This option is passed to the mysql child process.
-                It defines the socket to use when connecting to local database
-                server with UNIX domain socket.
-                Try 'mysql --help' for more details on this option.
-
-    --no-timestamp
-                This option prevents the creation of a new backup
-                directory (named by the current date and time) under
-                the backup root directory. Instead, the backup is put
-                in the directory given on the command-line (in the
-                place of BACKUP-ROOT-DIR argument). The directory must not 
-                exist, because innobackup creates it while making a backup.
-
-    --ibbackup=IBBACKUP-BINARY
-                Use this option to specify which ibbackup (InnoDB Hot
-                Backup) binary should be used.  IBBACKUP-BINARY
-                should be the command used to run ibbackup. This can
-                be useful if ibbackup is not in your search path or
-                working directory.  If this option is not given,
-                ibbackup is run with command "xtrabackup".
-    --no-lock
-                Use this option to disable table lock with
-                FLUSH TABLES WITH READ LOCK. use it only while ALL your 
-                tables are InnoDB and you DO NOT CARE about binary log 
-                position of backup.
-
-    --scpopt=SCP-OPTIONS
-                Use this option to specify the command line options
-                to pass to scp.  The default options are '-Cp -c arcfour'.
-
-EOF
+   my $msg = shift || '';
+   pod2usage({ -msg => $msg, -verbose => 1});
+   return 0;
 }
 
 
@@ -1769,23 +1543,11 @@
                 "Your perl is too old! Innobackup requires\n";
             print STDERR "$prefix Warning: perl $required_version or newer!\n";
         }
-    } else {
-        $perl_version = chr($required_perl_version[0])
-            . chr($required_perl_version[1])
-            . chr($required_perl_version[2]);
-        if ($^V lt $perl_version) {
-            my $version = chr(48 + $required_perl_version[0])
-                . "." . chr(48 + $required_perl_version[1])
-                . "." . chr(48 + $required_perl_version[2]);
-            print STDERR "$prefix Warning: " . 
-                "Your perl is too old! Innobackup requires\n";
-            print STDERR "$prefix Warning: perl $version or newer!\n";
-        }
     }
 
     if (@ARGV == 0) {
         # no command line arguments
-        usage();
+        print STDERR "$prefix You must specify the backup directory.\n";
         exit(1);
     }
 
@@ -1799,8 +1561,8 @@
                         'redo-only' => \$option_redo_only,
                         'copy-back' => \$option_copy_back,
                         'include=s' => \$option_include,
-			'databases=s' => \$option_databases,
-         'tables-file=s', => \$option_tables_file,
+                        'databases=s' => \$option_databases,
+                        'tables-file=s', => \$option_tables_file,
                         'use-memory=s' => \$option_use_memory,
                         'uncompress' => \$option_uncompress,
                         'export' => \$option_export,
@@ -1832,7 +1594,6 @@
     if (!$rcode) {
         # failed to read options
         print STDERR "$prefix Bad command line arguments\n";
-        usage();
         exit(1);
     }
     if ($option_help) {
@@ -1858,11 +1619,9 @@
 
     if (@ARGV < 1) {
         print STDERR "$prefix Missing command line argument\n";
-        usage();
         exit(1);
     } elsif (@ARGV > 1) {
         print STDERR "$prefix Too many command line arguments\n";
-        usage();
         exit(1);
     }
 
@@ -2569,3 +2328,216 @@
    my ($n) = $lines[$last_value] =~ m/(\d+)/;
    return $n;
 }
+
+=pod
+
+=head1 NAME
+
+innobackupex - Non-blocking backup tool for InnoDB, XtraDB and HailDB databases
+
+=head1 SYNOPOSIS
+
+innobackupex [--compress[=LEVEL]] [--include=REGEXP] [--user=NAME] 
+             [--password=WORD] [--port=PORT] [--socket=SOCKET]
+             [--no-timestamp] [--ibbackup-binary=IBBACKUP-BINARY]
+             [--slave-info] [--stream=tar] [--force-tar]
+             [--scpopt=OPTIONS-FOR-SCP] [--defaults-file=MY.CNF]
+             [--databases=LIST] [--remote-host=HOSTNAME] [--no-lock] 
+             [--tmpdir=DIRECTORY] [--tables-file=FILE]
+             [--incremental] [--incremental-basedir]
+             [--incremental-dir] [--incremental-lsn]
+             BACKUP-ROOT-DIR
+
+innobackupex --apply-log [--use-memory=MB] [--uncompress]
+             [--defaults-file=MY.CNF]
+             [--export] [--redo-only] [--ibbackup=IBBACKUP-BINARY]
+             BACKUP-DIR
+
+innobackupex --copy-back [--defaults-file=MY.CNF] BACKUP-DIR
+
+=head1 DESCRIPTION
+
+The first command line above makes a hot backup of a MySQL database.
+By default it creates a backup directory (named by the current date
+and time) in the given backup root directory.  With the --no-timestamp
+option it does not create a time-stamped backup directory, but it puts
+the backup in the given directory (which must not exist).  This
+command makes a complete backup of all MyISAM and InnoDB tables and
+indexes in all databases or in all of the databases specified with the
+--databases option.  The created backup contains .frm, .MRG, .MYD,
+.MYI, .TRG, .TRN, .ARM, .ARZ, .CSM, CSV, .opt, .par, and InnoDB data and log files.
+The MY.CNF options file defines the location of the database.  This command
+connects to the MySQL server using the mysql client program, and runs
+xtrabackup as a child process.
+
+The --apply-log command prepares a backup for starting a MySQL
+server on the backup. This command recovers InnoDB data files as specified
+in BACKUP-DIR/backup-my.cnf using BACKUP-DIR/xtrabackup_logfile,
+and creates new InnoDB log files as specified in BACKUP-DIR/backup-my.cnf.
+The BACKUP-DIR should be the path to a backup directory created by
+xtrabackup. This command runs xtrabackup as a child process, but it does not 
+connect to the database server.
+
+The --copy-back command copies data, index, and log files
+from the backup directory back to their original locations.
+The MY.CNF options file defines the original location of the database.
+The BACKUP-DIR is the path to a backup directory created by xtrabackup.
+
+On success the exit code innobackupex is 0. A non-zero exit code 
+indicates an error.
+
+
+=head1 OPTIONS
+
+=over
+
+=item --apply-log
+
+Prepare a backup in BACKUP-DIR by applying the transaction log file named "xtrabackup_logfile" located in the same directory. Also, create new transaction logs. The InnoDB configuration is read from the file "backup-my.cnf".
+
+=item --copy-back
+
+Copy all the files in a previously made backup from the backup directory to their original locations.
+
+=item --databases=LIST
+
+This option specifies the list of databases that innobackupex should back up.  The option accepts a string argument. The list is of the form "databasename1[.table_name1] databasename2[.table_name2] . . .". If this option is not specified, all databases containing MyISAM and InnoDB tables will be backed up. Please make sure that --databases contains all of the InnoDB databases and tables, so that all of the innodb.frm files are also backed up. In case the list is very long, this can be specified in a file, and the full path of the file can be specified instead of the list. (See option --tables-file.)
+
+=item --defaults-file=[MY.CNF]
+
+This option specifies what file to read the default MySQL options from.  The option accepts a string argument. It is also passed directly to xtrabackup's --defaults-file option. See the xtrabackup documentation for details.
+
+=item --export
+
+This option is passed directly to xtrabackup's --export option. It enables exporting individual tables for import into another server. See the xtrabackup documentation for details.
+
+=item --extra-lsndir=DIRECTORY
+
+This option specifies the directory in which to save an extra copy of the "xtrabackup_checkpoints" file.  The option accepts a string argument. It is passed directly to xtrabackup's --extra-lsndir option. See the xtrabackup documentation for details.
+
+=item --force-tar
+
+This option forces the use of tar when creating a streamed backup, rather than tar4ibd, which is the default.
+
+=item --help
+
+This option displays a help screen and exits.
+
+=item --host=HOST
+
+This option specifies the host to use when connecting to the database server with TCP/IP.  The option accepts a string argument. It is passed to the mysql child process without alteration. See mysql --help for details.
+
+=item --ibbackup-binary=IBBACKUP-BINARY
+
+This option specifies which xtrabackup binary should be used.  The option accepts a string argument. IBBACKUP-BINARY should be the command used to run XtraBackup. The option can be useful if the xtrabackup binary is not in your search path or working directory. If this option is not specified, innobackupex attempts to determine the binary to use automatically. By default, "xtrabackup" is the command used. However, when option --copy-back is specified, "xtrabackup_51" is the command used. And when option --apply-log is specified, the binary is used whose name is in the file "xtrabackup_binary" in the backup directory, if that file exists.
+
+=item --include=REGEXP
+
+This option is a regular expression to be matched against table names in databasename.tablename format. It is passed directly to xtrabackup's --tables option. See the xtrabackup documentation for details.
+
+=item --incremental
+
+This option tells xtrabackup to create an incremental backup, rather than a full one. It is passed to the xtrabackup child process. When this option is specified, either --incremental-lsn or --incremental-basedir can also be given. If neither option is given, option --incremental-basedir is passed to xtrabackup by default, set to the first timestamped backup directory in the backup base directory.
+
+=item --incremental-basedir=DIRECTORY
+
+This option specifies the directory containing the full backup that is the base dataset for the incremental backup.  The option accepts a string argument. It is used with the --incremental option.
+
+=item --incremental-dir=DIRECTORY
+
+This option specifies the directory where the incremental backup will be combined with the full backup to make a new full backup.  The option accepts a string argument. It is used with the --incremental option.
+
+=item --incremental-lsn
+
+This option specifies the log sequence number (LSN) to use for the incremental backup.  The option accepts a string argument. It is used with the --incremental option. It is used instead of specifying --incremental-basedir. For databases created by MySQL and Percona Server 5.0-series versions, specify the LSN as two 32-bit integers in high:low format. For databases created in 5.1 and later, specify the LSN as a single 64-bit integer.
+
+=item --no-lock
+
+Use this option to disable table lock with "FLUSH TABLES WITH READ LOCK". Use it only if ALL your tables are InnoDB and you DO NOT CARE about the binary log position of the backup.
+
+=item --no-timestamp
+
+This option prevents creation of a time-stamped subdirectory of the BACKUP-ROOT-DIR given on the command line. When it is specified, the backup is done in BACKUP-ROOT-DIR instead.
+
+=item --parallel=NUMBER-OF-THREADS
+
+This option specifies the number of threads the xtrabackup child process should use to back up files concurrently.  The option accepts an integer argument. It is passed directly to xtrabackup's --parallel option. See the xtrabackup documentation for details.
+
+
+=item --password=WORD
+
+This option specifies the password to use when connecting to the database. It accepts a string argument.  It is passed to the mysql child process without alteration. See mysql --help for details.
+
+=item --port=PORT
+
+This option specifies the port to use when connecting to the database server with TCP/IP.  The option accepts a string argument. It is passed to the mysql child process. It is passed to the mysql child process without alteration. See mysql --help for details.
+
+=item --redo-only
+
+This option is passed directly to xtrabackup's --apply-log-only option. This forces xtrabackup to skip the "rollback" phase and do a "redo" only. This is necessary if the backup will have incremental changes applied to it later. See the xtrabackup documentation for details. 
+
+=item --remote-host=HOSTNAME 
+
+This option specifies the remote host on which the backup files will be created, by using an ssh connection.  The option accepts a string argument.
+
+=item --safe-slave-backup
+
+Stop slave SQL thread and wait to start backup until Slave_open_temp_tables in "SHOW STATUS" is zero. If there are no open temporary tables, the backup will take place, otherwise the SQL thread will be started and stopped until there are no open temporary tables. The backup will fail if Slave_open_temp_tables does not become zero after --safe-slave-backup-timeout seconds. The slave SQL thread will be restarted when the backup finishes.
+
+=item --safe-slave-backup-timeout
+
+How many seconds --safe-slave-backup should wait for Slave_open_temp_tables to become zero. (default 300)
+
+=item --scpopt=SCP-OPTIONS
+
+This option specifies the command line options to pass to scp when the option --remost-host is specified.  The option accepts a string argument. If the option is not specified, the default options are "-Cp -c arcfour".
+
+=item --slave-info
+
+This option is useful when backing up a replication slave server. It prints the binary log position and name of the master server. It also writes this information to the "xtrabackup_slave_info" file as a "CHANGE MASTER" command. A new slave for this master can be set up by starting a slave server on this backup and issuing a "CHANGE MASTER" command with the binary log position saved in the "xtrabackup_slave_info" file.
+
+=item --socket=SOCKET
+
+This option specifies the socket to use when connecting to the local database server with a UNIX domain socket.  The option accepts a string argument. It is passed to the mysql child process without alteration. See mysql --help for details.
+
+=item --stream=[tar|. . .]
+
+This option specifies the format in which to do the streamed backup.  The option accepts a string argument. The backup will be done to STDOUT in the specified format. Currently, the only supported format is tar. Uses tar4ibd, which is available in XtraBackup distributions.
+
+=item --tables-file=FILE
+
+This option specifies the file in which there are a list of names of the form database.  The option accepts a string argument.table, one per line. The option is passed directly to xtrabackup's --tables-file option.
+
+=item --throttle=IOS
+
+This option specifies a number of I/O operations (pairs of read+write) per second.  It accepts an integer argument.  It is passed directly to xtrabackup's --throttle option.
+
+=item --tmpdir=DIRECTORY
+
+This option specifies the location where a temporary file will be stored.  The option accepts a string argument. It should be used when --remote-host or --stream is specified. For these options, the transaction log will first be stored to a temporary file, before streaming or copying to a remote host. This option specifies the location where that temporary file will be stored. If the option is not specifed, the default is to use the value of tmpdir read from the server configuration.
+
+=item --use-memory=MB
+
+This option specifies the amount of memory in megabytes for xtrabackup to use for crash recovery while preparing a backup.  The option accepts a string argument. It is used only with the option --apply-log. It is passed directly to xtrabackup's --use-memory option. See the xtrabackup documentation for details.
+
+=item --user=NAME
+
+This option specifies the MySQL username used when connecting to the server, if that's not the current user. The option accepts a string argument.  It is passed to the mysql child process without alteration. See mysql --help for details.
+
+=item --version
+
+This option displays the xtrabackup version and copyright notice and then exits.
+
+=back
+
+=head1 BUGS
+
+Bugs can be reported on Launchpad: https://bugs.launchpad.net/percona-xtrabackup/+filebug
+
+=head1 COPYRIGHT
+
+InnoDB Backup Utility Copyright 2003, 2009 Innobase Oy and Percona, Inc 2009-2011. All Rights Reserved.
+
+This software is published under the GNU GENERAL PUBLIC LICENSE Version 2, June 1991.
+
+=cut