1MYLVMBACKUP(1) User Contributed Perl Documentation MYLVMBACKUP(1)
2
6 mylvmbackup - a utility for creating MySQL backups using LVM snapshots
7
9 mylvmbackup [OPTIONS]
10
12 mylvmbackup is a tool for quickly creating full physical backups of a
13 MySQL server's data files. To perform a backup, mylvmbackup obtains a
14 read lock on all tables and flushes all server caches to disk, makes an
15 LVM snapshot of the volume containing the MySQL data directory, and
16 unlocks the tables again. The snapshot process takes only a small
17 amount of time. When it is done, the server can continue normal
18 operations, while the actual file backup proceeds.
19 The LVM snapshot is mounted to a temporary directory and all data is
21 backed up using the tar program by default. The archive files are
22 created using names in the form of backup-YYYYMMDD_hhmmss_mysql.tar.gz,
23 where YYYY, MM, DD, hh, mm and ss represent the year, month, day, hour,
24 minute, and second of the time at which the backup occurred. The
25 default prefix backup, date format and file suffix may be modified. The
26 use of timestamped archive names allows you to run mylvmbackup many
27 times without risking to overwrite old archives. It is possible to
28 preserve only a defined number of last backups, to avoid running out of
29 disk space.
30 Alternatively, instead of tar, you can use rsync, rsnap or zbackup to
32 perform the archiving.
33 The rsync backup can perform both local backups as well as backing up
35 to a remote server using rsyncd or rsync via SSH.
36 rsnap is a wrapper around rsync to automatically maintain and rotate a
38 given number of last backups (7 by default). It utilizes hard links to
39 link to unchanged files for saving disk space.
40 zbackup is a globally-deduplicating backup tool. Feed a large .tar into
42 it, and it will store duplicate regions of it only once, then compress
43 and optionally encrypt the result. Feed another .tar file, and it will
44 also re-use any data found in any previous backups. This way only new
45 changes are stored, and as long as the files are not very different,
46 the amount of storage required is very low. Any of the backup files
47 stored previously can be read back in full at any time.
48 Moreover, a backup type none is provided for cases where the user wants
50 to use mylvmbackup only for creating the snapshots and intends to
51 perform the actual backup by using the appropriate hooks. (Or for cases
52 where the snapshot itself is considered to be the backup).
53 mylvmbackup also provides several methods for logging and reporting the
55 progress and success of a backup run. The log messages can either be
56 printed to the console (STDOUT) or logged via syslog.
57 Additionally, a report can be sent to you via email, and you can
59 receive notifications about failures or successes via SNMP.
60
62 It is required to run mylvmbackup on the same host where the MySQL
63 server runs. If your MySQL daemon is not listening on localhost or
64 using the default socket location, you must specify --host or --socket.
65 Even though mylvmbackup communicates with the server through a normal
66 client connection to obtain the read lock and flush data, it performs
67 the actual backup by accessing the file system directly. It is also a
68 requirement that the MySQL server's data directory resides on an LVM
69 volume. (It is, however, a good idea to do the LVM backup to a
70 different partition than the one where the data directory resides.
71 Otherwise, there is a good chance that LVM will run out of undo space
72 for LVM snapshot maintenance and the backup will fail.)
73 The user who invokes mylvmbackup must have sufficient filesystem
75 permissions to create the LVM snapshot and mount it. This includes
76 read/write access to the backup directory.
77 If you plan to back up InnoDB tables using LVM snapshots, be advised
79 that it is not sufficient to lock the tables and issue the FLUSH TABLES
80 command to get the table files into a consistent state. When starting
81 the MySQL server from these restored files, InnoDB will detect these
82 tables as being in an inconsistent state and will perform a log
83 recovery run before the tables can be accessed again. As this can
84 potentially take some time (which you may not want to spend after
85 restoring a server and trying to get it back on its feet as fast as
86 possible), consider using the option --innodb_recover, which will
87 perform the recovery operation on the backup snapshot prior to
88 archiving it.
89 The recovery operation is performed by spawning a second mysqld
91 instance that uses the snapshot volume as the data directory. Note that
92 this functionality currently assumes a default InnoDB configuration in
93 which all InnoDB table spaces and log files are stored inside of the
94 data directory - it does not work properly if you use options like
95 --innodb-data-home-dir, --innodb-data-file-path or
96 --innodb-log-group-home-dir that modify the default file layout for
97 InnoDB tables.
98 If you use InnoDB tables exclusively, you may also want to consider to
100 include the option --skip_flush_tables, to avoid the probably time-
101 consuming and in this case unnecessary flushing of buffers. But don't
102 enable this option when MyISAM tables are involved!
103
105 It is possible to run arbitrary external programs or scripts (hooks) at
106 various stages of the backup process, to perform additional actions as
107 part of the backup process.
108 These scripts or symbolic links to executables should be placed in the
110 directory that the hooksdir configuration option points to
111 (/usr/share/mylvmbackup by default). They should return zero upon
112 successful completion, any non-zero return value will be considered a
113 failure which will be logged.
114 Hook scripts can also be implemented as Perl modules. The module must
116 be named hookname.pm and must be a package of type hookname. The module
117 must implement execute() which is called by mylvmbackup to initiate the
118 hook. It must return boolean true/false (1 or 0) on success/failure.
119 execute() will be passed 2 parameters. The first parameter is a clone()
120 of the global database handle $dbh. This will allow hook scripts to
121 interact with the database using the established connection. The
122 second parameter is a string containing any messages passed to the
123 run_hook() function. The module must also implement errmsg() which
124 will return a string error message to be sent to log_msg(). This will
125 be called by mylvmbackup when execute() returns false/0.
126 The names of the scripts or symbolic links reflect the stage in which
128 the hook will be called. Currently, the following stages exist:
129 preconnect
131 before a connection to the database server is established
132 preflush
134 before calling FLUSH TABLES
135 presnapshot
137 before the file system snapshot is created
138 preunlock
140 before the database tables are unlocked again
141 predisconnect
143 before the connection to the database server is released
144 premount
146 before the snapshot volume is mounted
147 prebackup
149 before the snapshot backup will be performed
150 backupsuccess
152 after a successful backup
153 backupfailure
155 after a failed backup
156 logerr
158 when an error is logged
159 precleanup
161 before the snapshot is unmounted and discarded
162 These hooks are optional and will only be called if a file for the
164 particular stage exists and is executable. Note that hooks implemented
165 as Perl modules (hookname.pm) have priority over "plain" hook scripts
166 (hookname), if both exist, only the first one will be used. The
167 execution of all hooks can be suppressed by passing the --skip_hooks
168 option or by setting the skip_hooks configuration option to 1;
169
171 mylvmbackup supports the following command line options. The same
172 options can also be defined in the /etc/mylvmbackup.conf configuration
173 file (omitting the leading dashes, of course). A sample configuration
174 file is included in the distribution.
175 --action=string
177 Selects the mode of action. Possible values are backup and purge.
178 When this option is omitted, the backup action is assumed by
180 default, which performs the actual backup creation. Older backup
181 files are preserved.
182 The purge action can be used to remove older tar or local rsync
184 backups from the backup directory, except for the a configurable
185 number of most recent backups, defined by the backupretention
186 option. The backup creation process is skipped in this case.
187 Note that this option erases all files contained in this directory
189 that match the criterion of being older than the last n backup
190 files (with the exception of hidden (dot) files!
191 --user=string
193 Specifies the username to use for connecting to the MySQL server.
194 The default is root.
195 --password=string
197 Specifies the password to use for connecting to the MySQL server.
198 The default is the empty string (no password). Alternatively, you
199 can set the password by defining the environment variable MYSQL_PWD
200 prior to starting the script. Note however that this method is
201 considered to be highly insecure, as it's possible for other users
202 to obtain the password by examining the environment variables of
203 the running process. See the MySQL Reference manual for more
204 details on password security.
205 --host=string
207 Specifies the host name to use for connecting to the MySQL server.
208 Note that mylvmbackup needs to be run on the same system that the
209 MySQL server to be backed up runs on - do not enter a remote host's
210 host name or IP address here! A non-empty value for host other
211 than localhost overrides any given socket path value. The default
212 is the empty string.
213 --port=number
215 Specifies the TCP port number to use for connecting to the MySQL
216 server. This value is only honoured, if host is provided as well
217 and is not equal to localhost. The default is the empty string.
218 --socket=string
220 Specifies the path to the local socket file, if it is not located
221 at the default location. The default is the empty string.
222 --quiet
224 Suppresses logging of informal messages. Warnings and errors will
225 still be printed or logged (depending on the selected logging
226 mechanism). The default is verbose logging.
227 --innodb_recover
229 Run InnoDB recovery on the writable snapshot prior to performing
230 the backup.
231 --recoveryopts
233 Additional values to pass to the startup options of the separate
234 MySQL instance that gets spawned to perform the InnoDB log recovery
235 option. Depending on your MySQL Server version, you may have to
236 modify these startup parameters.
237 The default is --skip-networking --skip-grant --bootstrap
239 --skip-syslog --skip-slave-start.
240 --skip_flush_tables
242 Don't issue a FLUSH TABLES WITH READ LOCK command before creating
243 the snapshot. Only use this option when backing up InnoDB tables
244 (as they don't support this function anyway and will require
245 recovery in any case). This option skips the (probably time
246 consuming) flushing of buffers.
247 --extra_flush_tables
249 If your database performs a lot of writes, it may help to perform
250 an extra initial FLUSH TABLES so that the lvcreate can finish
251 within the interactivity timeout during the read-locked flush.
252 --pidfile=string
254 Specifies the full path and file name to the PID file of the server
255 instance that is spawned to perform the InnoDB recovery (see option
256 --innodb_recover). Must be different from the PID file that the
257 actual running server uses. The default is
258 /var/tmp/mylvmbackup_recoverserver.pid
259 --lvcreate=string
261 Specifies the pathname for the lvcreate program. The default is
262 lvcreate.
263 --lvremove=string
265 Specifies the pathname for the lvremove program. The default is
266 lvremove.
267 --lvs=string
269 Specifies the pathname for the lvs program. The default is lvs.
270 --mysqld_safe=string
272 Specifies the pathname for the mysqld_safe program. The default is
273 mysqld_safe. Only used to perform InnoDB recovery.
274 --mycnf=string
276 Specifies the name of a MySQL config file (e.g. /etc/my.cnf) or an
277 entire config directory (e.g. /etc/mysql) to include in the backup.
278 The default is /etc/my.cnf.
279 --skip_mycnf
281 Skip backing up the MySQL configuration. The default is to include
282 a copy of the MySQL configuration in the backup.
283 --hooksdir=string
285 The location of external scripts or executable to be called during
286 various stages of the backup. See the HOOKS section in this manual
287 page for more info. The default is /usr/share/mylvmbackup.
288 --skip_hooks
290 Skip invoking any external hooks during the backup.
291 --vgname=string
293 Specifies the volume group of the logical volume where the MySQL
294 data directory is located. The default is mysql.
295 --lvname=string
297 Specifies the name of the logical volume where the MySQL data
298 directory is located. The default is data.
299 --backuplv=string
301 Specifies the name used for the snapshot volume. If left empty,
302 _snapshot will simply be appended to the original volume name (e.g.
303 data_snapshot).
304 It is possible to use selected timestr() formatting sequences to
306 create snapshot volume names which contain a dynamic date value.
307 This can be useful if you use thin provisioned snapshots as the
308 actual backup, by enabling the keep_snapshot option.
309 Currently, the following format strings are supported:
311 %Y 4-digit year (e.g. 2009)
313 %m Month (01..12)
315 %d Day of month, leading zero
317 %h Month abbreviation,
319 %H Hour, 24 hour clock, leading zero
321 %M Minute, leading zero
323 %S Seconds, leading zero
325 Example: $backuplv=backup-%Y-%m-%d-%H-%M-%S will expand to
327 backup-2013-06-07-14-08-45.
328 --keep_snapshot
330 If this option is given, mylvmbackup will not remove the snapshot
331 before terminating. Note that keeping multiple LVM snapshots open
332 at the same time can reduce I/O performance and you will need to
333 manually discard the snapshot before invoking mylvmbackup again.
334 --keep_mount
336 If this option is given, mylvmbackup will not remove the mounted
337 partition before terminating. This option also implies
338 keep_snapshot=1, as it would not be useful if the snapshot is
339 removed. You need to manually unmount this directory before
340 invoking mylvmbackup again.
341 --thin
343 If this option is given, mylvmbackup will expect that the LVM
344 volume is using thin provisioning and that the snapshot will use
345 physical space from the existing thin pool. Any size specified with
346 lvsize is ignored.
347 --relpath=string
349 Relative path on the logical volume to the MySQL data directory (no
350 leading or trailing slash). Example: the logical volume is mounted
351 on /var/lib, but the MySQL data directory is /var/lib/mysql. In
352 this case, relpath should be set to mysql. The default is the
353 empty string.
354 --lvsize=string
356 Specifies the size for the snapshot volume. The default is 5G (5
357 gigabytes).
358 --backuptype=string
360 Specifies what type of backup to perform. The available options are
361 tar, rsync, rsnap, zbackup and none. Note that using zbackup still
362 requires a tar executable to prepare the backup archives.
363 --backupretention=string
365 Specifies how many previous backups (tar archives or rsync
366 directories only) to keep in the backup directory when performing
367 the purge action. The default is 0 (keep all backups).
368 Note that this feature only works on a local backup directory with
370 a static directory name! If you use timestr() formatting sequences
371 for the backup directory, the retention mode will not work.
372 The script looks at the last modification time (mtime) of each file
374 and directory to determine which files will be removed.
375 Be advised that this operation deletes all files and directories in
377 the backup directory that are older than the last n files (with the
378 exception of hidden (dot) files!
379 --prefix=string
381 Prefix added to the backup file names. It is also appended to the
382 name of the directory used to mount the snapshot volume. The
383 default value is backup.
384 --suffix=string
386 Suffix added to the backup file names (after the time stamp). The
387 default value is _mysql.
388 --datefmt=string
390 Format of the time stamp included in the backup file name. See the
391 Date::Format perldoc page for a description of the format. The
392 default value is %Y%m%d_%H%M%S, which creates a time stamp like
393 YYYYMMDD_HHMMSS, e.g. 20070531_112549 Can be empty as well, to
394 suppress adding a time stamp (e.g. when using rsync to always sync
395 into the same backup directory).
396 --mountdir=string
398 Path for mounting the snapshot volume to. The default value is
399 /var/tmp/mylvmbackup/mnt/. If the directory does not exist, it
400 will be created.
401 It is possible to use selected timestr() formatting sequences to
403 create directory names which contain a dynamic date value.
404 Currently, the following format strings are supported:
405 %Y 4-digit year (e.g. 2009)
407 %m Month (01..12)
409 %d Day of month, leading zero
411 %h Month abbreviation,
413 %H Hour, 24 hour clock, leading zero
415 %M Minute, leading zero
417 %S Seconds, leading zero
419 Example: $mountdir=/path/to/%Y-%m-%d will expand to
421 /path/to/2009-06-13
422 --backupdir=string
424 Specifies the pathname of the directory where the archive files
425 will be written to. The backup directory must not be on the same
426 volume as the MySQL data directory. If the directory does not
427 exist, it will be created.
428 It is possible to use selected timestr() formatting sequences to
430 create directory names which contain a dynamic date value.
431 Currently, the following format strings are supported:
432 %Y 4-digit year (e.g. 2009)
434 %m Month (01..12)
436 %d Day of month, leading zero
438 %h Month abbreviation,
440 %H Hour, 24 hour clock, leading zero
442 %M Minute, leading zero
444 %S Seconds, leading zero
446 Example: $mountdir=/path/to/%Y-%m-%d will expand to
448 /path/to/2009-06-13
449 Instead of a local directory, you can also provide a valid rsync
451 URL here, e.g. username@hostname:/path, hostname:path or
452 hostname::rsync-module/path. This requires a properly configured
453 remote rsync setup (e.g. pre-setup SSH keys or a working rsyncd
454 configuration).
455 Note that the backupretention option does not work for rsync URLs
457 or directory names that use format strings. You need to define a
458 static local directory name in backupdir if you want to use the
459 purge action to automatically remove older backups from the backup
460 directory.
461 The default is /var/tmp/mylvmbackup/backup/
463 --mount=string
465 Specifies the pathname for the mount program. The default is
466 mount.
467 --umount=string
469 Specifies the pathname for the umount program. The default is
470 umount.
471 --tar=string
473 Specifies the pathname for the tar program. The default is tar.
474 --tararg=string
476 Specifies the initial arguments for the tar program. The default
477 is cvf.
478 --tarsuffixarg=string
480 Specifies the suffix arguments for the tar program. The default is
481 the empty string. To exclude a database, you would pass --exclude
482 dbname here.
483 --tarfilesuffix=string
485 Specifies the suffix for the tarball. This value should be set
486 according to the selected compression method (e.g. .tar.bz2 for
487 bzip2 compression). The default is .tar.gz.
488 --compress=string
490 Specifies the name of the compression program. Only used if
491 backuptype is set to tar. Some possibilities are gzip, bzip2 or
492 lzma. The program must support reading the to be compressed data
493 from stdin and writing to stdout, without requiring intermediate
494 temporary files (for this reason, 7zip cannot be used). It's also
495 possible to use cat. In this case, no compression will be done.
496 Make sure to update the compressarg option and the tarfilesuffix
497 accordingly. The default is gzip. Can be left empty.
498 --compressarg=string
500 Specifies the command line options given to the compress program.
501 For gzip, that would be --stdout --verbose --best, for lzma or
502 bzip2 --stdout --verbose -7 and for cat, it would be empty. The
503 default is --stdout --verbose --best.
504 --rsnap=string
506 Specifies the pathname for the rsnap program. The default is
507 rsnap.
508 --rsnaparg=string
510 Specifies the arguments for the rsnap program. The default is 7,
511 which causes it to keep the last 7 snapshot (useful when running
512 mylvmbackup once per day).
513 --rsnaprsyncarg=string
515 Specifies the arguments for the rsync process that is spawned by
516 rsnap, e.g. --exclude \*.o --bwlimit=8. You don't need to provide
517 the double dashes usually required by rsnap to separate these
518 arguments. Default value is the empty string.
519 --rsync=string
521 Specifies the pathname for the rsync program. The default is
522 rsync.
523 --rsyncarg=string
525 Specifies the arguments for the rsync program. The default is
526 -avWP. You must ensure that the recursive option is included either
527 implicitly by -a, or explicitly by using -r.
528 --zbackup=string
530 Specifies the pathname for the zbackup program. The default is
531 zbackup.
532 --zbackuparg=string
534 Specifies the arguments for the zbackup program. The default is
535 --non-encrypted.
536 You may use --password-file /path/to/pass to create an encrypted
538 zbackup repository. The backup repository located in backupdir will
539 be initialized automatically by running zbackup init before the
540 first invocation.
541 --xfs
543 Use the nouuid mount option to safely mount snapshot partitions
544 that use the XFS file system.
545 --log_method=string
547 How to log output from this script. Valid options are console,
548 syslog or both. The default value is console. Enabling the syslog
549 option requires an installed Sys::Syslog Perl module.
550 --syslog_socktype=string
552 What type of socket to use for connecting to the syslog service.
553 Valid options are native, tcp and udp. The default value is
554 native.
555 --syslog_facility=string
557 Define a particular syslog facility Default value is the empty
558 string.
559 --syslog_remotehost=string
561 Host name of a remote syslog server.
562 --mail_report_on=string
564 Enable sending the logging output via email to a specified email
565 address.
566 This option requires an installed MIME::Lite Perl module as well as
568 a functional local sendmail (or alternative) facility.
569 You should also review and adjust the mail_from, mail_to and
571 mail_subject configuration options to match you requirements.
572 Supported values are never, this disables the mail reporting
574 completely. A value of always sends an email report for each
575 invocation of mylvmbackup, errors only sends a report in case of an
576 error condition.
577 The default value is never.
579 --mail_from=string
581 The email address to be used in the From: header for email reports
582 (requires the mail_report option to be set). The default value is
583 root@localhost.
584 --mail_to=string
586 The email address to be used to send email reports to (requires the
587 mail_report option to be set). The default value is
588 root@localhost.
589 --mail_subject=string
591 The text to be used in the Subject: header for email reports
592 (requires the mail_report option to be set). The default value is
593 "mylvmbackup report for localhost".
594 --snmp_report_on=string
596 Enable sending SNMP traps to specified SNMP target hosts.
597 This option requires an installed Net::SNMP Perl module.
599 You should also review and adjust the snmp_base_oid, snmp_targets,
601 snmp_community snmp_port configuration options to match you
602 requirements.
603 Supported values are never, this disables sending SNMP traps
605 completely. A value of always sends an SNMP trap for each
606 invocation of mylvmbackup, errors only sends an SNMP trap in case
607 of an error condition.
608 The default value is never.
610 --snmp_base_oid=string
612 The SNMP object identifier (OID) in dotted notation. The default
613 is 1.3.6.1.4.1.0.0.
614 --snmp_targets=string
616 A comma-separated list of host names or IP addresses to send SNMP
617 traps to. The default is localhost.
618 --snmp_community=string
620 The SNMP community name. The default is public.
621 --snmp_port=number
623 The TCP port on the target host to send SNMP traps to. The default
624 is 162.
625 --configfile=string
627 Specify an alternative configuration file. The default is
628 /etc/mylvmbackup.conf.
629 --help
631 Displays a help message showing the available options.
632
634 /etc/mylvbackup.conf
635 The mylvmbackup configuration file
636 mylvmbackup
638 The executable Perl script that performs the work.
639
641 For proper operation mylvmbackup requires Perl 5 with the DBI and
642 DBD::mysql modules. It also needs the Config::IniFiles to read the
643 global configuration file of the program. Date::Format is required to
644 create the time stamp used in the backup file names. In addition, it
645 utilizes Getopt::Long, File::Basename and File::Temp, which usually are
646 part of the default Perl distribution. File::Copy::Recursive is used
647 to copy the MySQL configuration file(s). Sys::Syslog is only required
648 in case you want to enable the syslog log facility. The MIME::Lite
649 module is required when you enable the mail reporting functionality. It
650 also requires a functional local sendmail (or alternative) facility.
651 It also requires several other external programs: GNU tar and gzip to
653 back up the data, LVM utilities (lvcreate, lvremove and lvs) to create
654 and remove the LVM snapshot, and the system utilities mount and umount.
655 Please note that mylvmbackup requires Linux LVM Version 2 or higher. It
656 does not work on LVMv1, as this version does not support writable
657 snapshots.
658 Optionally, rsync or rsnap may be required instead of tar and gzip,
660 depending on which backup type you choose.
661
663 mount(8), tar(1), lvcreate(8), lvremove(8), lvs(8), umount(8), rsync(1)
664
666 This program was initially written by Aleksey "Walrus" Kishkin from
667 MySQL AB, with suggestions from Peter Zaitsev and Lenz Grimmer.
668 It is currently maintained by Lenz Grimmer <lenz@grimmer.com>
670
672 Main web site: <http://www.lenzg.net/mylvmbackup>
673 Mailing list: <https://launchpad.net/~mylvmbackup-discuss>
675 Source code, bug tracker: <https://launchpad.net/mylvmbackup>
677
679 See the file CREDITS included in the distribution for a list of
680 individual contributors.
681
683 mylvmbackup is distributed under the GNU public license. See the file
684 COPYING for details.
685perl v5.18.2 2014-11-21 MYLVMBACKUP(1)