MYLVMBACKUP(1)

📦
version 0.15 · 4 versions
, in ubuntu jammy

💖 MYLVMBACKUP 💖

okay bestie, gather round, because this is the mylvmbackup manual page from the User Contributed Perl Documentation section, and it's a whole vibe. it's a utility for creating MySQL backups using LVM snapshots. yes. we're doing real sysadmin stuff today. 💅

✨ SYNOPSIS ✨

mylvmbackup [OPTIONS]

that's it. that's the whole summoning ritual. 🎀

🌸 DESCRIPTION 🌸

so mylvmbackup is the tool you call when you want to make full physical backups of a MySQL server's data files, and you want them fast. like, "the server barely notices" fast. the way it works is honestly iconic: it grabs a read lock on all the tables, flushes every server cache to disk, makes an LVM snapshot of the volume holding the MySQL data directory, and then unlocks the tables again. the snapshot step takes only a tiny little moment ✨. once it's done, the server just goes back to doing its thing while the actual file backup chugs along in the background. main character server energy, honestly.

the LVM snapshot gets mounted to a temporary directory and all the data is backed up using the tar program by default. the archive files get names in the form of backup-YYYYMMDD_hhmmss_mysql.tar.gz, where YYYY, MM, DD, hh, mm and ss stand for the year, month, day, hour, minute, and second of the moment the backup happened. cute, right? and the default prefix backup, the date format and the file suffix are all modifiable, so you can make it yours. the timestamped archive names mean you can run mylvmbackup over and over without risking overwriting your old archives — no cap. and if you're worried about disk space, you can preserve only a defined number of last backups. obsessed.

alternatively, instead of tar, you can use rsync, rsnap or zbackup to do the archiving. let's talk about them:

  • rsync — can do both local backups and backing up to a remote server using rsyncd or rsync via SSH. remote glow-up 🦋
  • rsnap — a wrapper around rsync that automatically maintains and rotates a given number of last backups (7 by default). it uses hard links to link to unchanged files so you save disk space. it's giving efficient.
  • zbackup — a globally-deduplicating backup tool. feed a large .tar into it and it stores duplicate regions of it only once, then compresses and optionally encrypts the result. feed it another .tar file and it will also re-use any data found in any previous backups. so only new changes get stored, and as long as the files aren't very different, the amount of storage required is very low. any of the backup files stored previously can be read back in full at any time. literally magic 🧚

moreover, there's a backup type none for when you just want mylvmbackup to create the snapshots and you plan to do the actual backup yourself using the appropriate hooks. (or for when the snapshot itself is the backup. valid.) 👑

mylvmbackup also provides several methods for logging and reporting the progress and success of a backup run. log messages can either be printed to the console (STDOUT) or logged via syslog. and as a little treat, a report can be sent to you via email. 💌

🫶 GENERAL HINTS 🫶

you must run mylvmbackup on the same host where the MySQL server runs. same host, bestie, no long distance. if your MySQL daemon isn't listening on localhost or is using a non-default socket location, you have to specify --host or --socket. even though mylvmbackup talks to the server through a normal client connection to get the read lock and flush data, it does the actual backup by accessing the file system directly. also required: the MySQL server's data directory has to live on an LVM volume. (that said, it's a good idea to do the LVM backup to a different partition than the one where the data directory resides. otherwise there's a good chance LVM will run out of undo space for LVM snapshot maintenance and the backup will fail. 💀)

the user who invokes mylvmbackup must have sufficient filesystem permissions to create the LVM snapshot and mount it. this includes read/write access to the backup directory.

if you plan to back up InnoDB tables using LVM snapshots, be advised: it is not sufficient to lock the tables and issue the FLUSH TABLES command to get the table files into a consistent state. 😭 when starting the MySQL server from these restored files, InnoDB will detect these tables as being in an inconsistent state and will perform a log recovery run before the tables can be accessed again. as this can potentially take some time (which you may not want to spend after restoring a server and trying to get it back on its feet as fast as possible), consider using the option --innodb_recover, which will perform the recovery operation on the backup snapshot prior to archiving it.

the recovery operation is performed by spawning a second mysqld instance that uses the snapshot volume as the data directory. note that this functionality currently assumes a default InnoDB configuration in which all InnoDB table spaces and log files are stored inside of the data directory — it does not work properly if you use options like --innodb-data-home-dir, --innodb-data-file-path or --innodb-log-group-home-dir that modify the default file layout for InnoDB tables.

if you use InnoDB tables exclusively, you may also want to consider including the option --skip_flush_tables, to avoid the probably time-consuming and in this case unnecessary flushing of buffers. but don't enable this option when MyISAM tables are involved! 🚨

🎀 HOOKS 🎀

yes bestie, you can run arbitrary external programs or scripts — hooks — at various stages of the backup process, to perform additional actions as part of the backup process. it's giving customizable.

these scripts, or symbolic links to executables, should be placed in the directory that the hooksdir configuration option points to (/usr/share/mylvmbackup by default). they should return zero upon successful completion — any non-zero return value will be considered a failure, which will be logged. 📝

hook scripts can also be implemented as Perl modules. the module must be named hookname.pm and must be a package of type hookname. the module must implement execute() which is called by mylvmbackup to initiate the hook. it must return boolean true/false (1 or 0) on success/failure. execute() will be passed 2 parameters. the first parameter is a clone() of the global database handle $dbh. this will allow hook scripts to interact with the database using the established connection. the second parameter is a string containing any messages passed to the run_hook() function. the module must also implement errmsg() which will return a string error message to be sent to log_msg(). this will be called by mylvmbackup when execute() returns false/0.

the names of the scripts or symbolic links reflect the stage in which the hook will be called. currently, the following stages exist:

  • preconnect — before a connection to the database server is established
  • preflush — before calling FLUSH TABLES
  • presnapshot — before the file system snapshot is created
  • preunlock — before the database tables are unlocked again
  • predisconnect — before the connection to the database server is released
  • premount — before the snapshot volume is mounted
  • prebackup — before the snapshot backup will be performed
  • backupsuccess — after a successful backup
  • backupfailure — after a failed backup
  • logerr — when an error is logged
  • precleanup — before the snapshot is unmounted and discarded

these hooks are optional and will only be called if a file for the particular stage exists and is executable. note that hooks implemented as Perl modules (hookname.pm) have priority over "plain" hook scripts (hookname) — if both exist, only the first one will be used. the execution of all hooks can be suppressed by passing the --skip_hooks option or by setting the skip_hooks configuration option to 1. slay 💅

⭐ OPTIONS ⭐

mylvmbackup supports the following command line options. the same options can also be defined in the /etc/mylvmbackup.conf configuration file (omitting the leading dashes, of course). a sample configuration file is included in the distribution. 🍓

  • --action=string — selects the mode of action. possible values are backup and purge.

when this option is omitted, the backup action is assumed by default, which performs the actual backup creation. older backup files are preserved.

the purge action can be used to remove older tar or local rsync backups from the backup directory, except for the a configurable number of most recent backups, defined by the backupretention option. the backup creation process is skipped in this case.

note that this option erases all files contained in this directory that match the criterion of being older than the last n backup files (with the exception of hidden (dot) files!

  • --user=string — specifies the username to use for connecting to the MySQL server. the default is root.
  • --password=string — specifies the password to use for connecting to the MySQL server. the default is the empty string (no password). alternatively, you can set the password by defining the environment variable MYSQL_PWD prior to starting the script. note however that this method is considered to be highly insecure, as it's possible for other users to obtain the password by examining the environment variables of the running process. see the MySQL Reference manual for more details on password security. 🙈
  • --host=string — specifies the host name to use for connecting to the MySQL server. note that mylvmbackup needs to be run on the same system that the MySQL server to be backed up runs on — do not enter a remote host's host name or IP address here! a non-empty value for host other than localhost overrides any given socket path value. the default is the empty string.
  • --port=number — specifies the TCP port number to use for connecting to the MySQL server. this value is only honoured if host is provided as well and is not equal to localhost. the default is the empty string.
  • --socket=string — specifies the path to the local socket file, if it is not located at the default location. the default is the empty string.
  • --quiet — suppresses logging of informal messages. warnings and errors will still be printed or logged (depending on the selected logging mechanism). the default is verbose logging.
  • --innodb_recover — run InnoDB recovery on the writable snapshot prior to performing the backup.
  • --recoveryopts — additional values to pass to the startup options of the separate MySQL instance that gets spawned to perform the InnoDB log recovery option. depending on your MySQL Server version, you may have to modify these startup parameters.

the default is --skip-networking --skip-grant --bootstrap --skip-syslog --skip-slave-start.

okay we're not done yet — this page is long and part 2 is coming right up, so don't go anywhere bestie 🦋

  • --skip_flush_tables — bestie, this one says don't run FLUSH TABLES WITH READ LOCK before the snapshot gets made. Only use it when you're backing up InnoDB tables (they don't support this function anyway and will need recovery in any case, so like… it's giving nothing). What it does do is skip the flushing of buffers, which is probably time consuming. So it's a speed flex, but only under those exact conditions. 🫶
  • --extra_flush_tables — if your database does a lot of writes, it may help to perform an extra initial FLUSH TABLES so that the lvcreate can finish within the interactivity timeout during the read-locked flush. Lowkey a little pre-flush pep talk for your storage layer. ✨
  • --pidfile=string — specifies the full path and file name to the PID file of the server instance that gets spawned to perform the InnoDB recovery (peep --innodb_recover). Must be different from the PID file that the actual running server uses. The default is /var/run/mysqld/mylvmbackup_recoverserver.pid. No sharing, that's the rule. 💅
  • --lvcreate=string — specifies the pathname for the lvcreate program. The default is lvcreate.
  • --lvremove=string — specifies the pathname for the lvremove program. The default is lvremove.
  • --lvs=string — specifies the pathname for the lvs program. The default is lvs.
  • --mysqld_safe=string — specifies the pathname for the mysqld_safe program. The default is mysqld_safe. Only used to perform InnoDB recovery.
  • --mycnf=string — the name of a MySQL config file (like /etc/my.cnf) or a whole entire config directory (like /etc/mysql) to include in the backup. The default is /etc/my.cnf. Yes bestie, you can absolutely hand it a directory. 👑
  • --skip_mycnf — skip backing up the MySQL configuration. The default behaviour is to include a copy of the MySQL configuration in the backup, so this is you saying "nah, not today". 🙈
  • --hooksdir=string — the location of external scripts or executable to be called during various stages of the backup. Go read the HOOKS section in this manual page for more info, fr. The default is /usr/share/mylvmbackup.
  • --skip_hooks — skip invoking any external hooks during the backup. The hooks are literally not invited to the function. 💀
  • --vgname=string — the volume group of the logical volume where the MySQL data directory lives. The default is mysql.
  • --lvname=string — the name of the logical volume where the MySQL data directory lives. The default is data.
  • --backuplv=string — the name used for the snapshot volume. If you leave it empty, _snapshot just gets appended to the original volume name (e.g. data_snapshot). So simple, so iconic.

You can also use selected timestr() formatting sequences to make snapshot volume names with a dynamic date value in them. This is useful if you use thin provisioned snapshots as the actual backup, by enabling the keep_snapshot option. 🦋

Currently, the following format strings are supported:

  • %Y — 4-digit year (e.g. 2009)
  • %m — Month (01..12)
  • %d — Day of month, leading zero
  • %h — Month abbreviation,
  • %H — Hour, 24 hour clock, leading zero
  • %M — Minute, leading zero
  • %S — Seconds, leading zero

Example: $backuplv=backup-%Y-%m-%d-%H-%M-%S will expand to backup-2013-06-07-14-08-45. Ate, no crumbs. 🌸

  • --keep_snapshot — if this option is given, mylvmbackup will not remove the snapshot before terminating. Note that keeping multiple LVM snapshots open at the same time can reduce I/O performance and you will need to manually discard the snapshot before invoking mylvmbackup again. So it's a "keep it" but also a "you clean it up", bestie. 😭
  • --keep_mount — if this option is given, mylvmbackup will not remove the mounted partition before terminating. This option also implies keep_snapshot=1, as it would not be useful if the snapshot is removed. You need to manually unmount this directory before invoking mylvmbackup again. Manual labour, unfortunately. 🫶
  • --thin — if this option is given, mylvmbackup will expect that the LVM volume is using thin provisioning and that the snapshot will use physical space from the existing thin pool. Any size specified with lvsize is ignored. Size? Don't know her. 💅
  • --relpath=string — relative path on the logical volume to the MySQL data directory (no leading or trailing slash). Example: the logical volume is mounted on /var/lib, but the MySQL data directory is /var/lib/mysql. In this case, relpath should be set to mysql. The default is the empty string.
  • --lvsize=string — specifies the size for the snapshot volume. The default is 5G (5 gigabytes). Chunky. 🎀
  • --backuptype=string — specifies what type of backup to perform. The available options are tar, rsync, rsnap, zbackup and none. Note that using zbackup still requires a tar executable to prepare the backup archives. iykyk. ✨
  • --backupretention=string — specifies how many previous backups (tar archives or rsync directories only) to keep in the backup directory when performing the purge action. The default is 0 (keep all backups).

Note that this feature only works on a local backup directory with a static directory name! If you use timestr() formatting sequences for the backup directory, the retention mode will not work.

The script looks at the last modification time (mtime) of each file and directory to determine which files will be removed.

Be advised that this operation deletes all files and directories in the backup directory that are older than the last n files (with the exception of hidden (dot) files!
  • --prefix=string — prefix added to the backup file names. It is also appended to the name of the directory used to mount the snapshot volume. The default value is backup.
  • --suffix=string — suffix added to the backup file names (after the time stamp). The default value is _mysql.
  • --datefmt=string — format of the time stamp included in the backup file name. See the Date::Format perldoc page for a description of the format. The default value is %Y%m%d_%H%M%S, which creates a time stamp like YYYYMMDD_HHMMSS, e.g. 20070531_112549. It can be empty as well, to suppress adding a time stamp (e.g. when using rsync to always sync into the same backup directory). Blank but valid, love that for her. 💜
  • --mountdir=string — path for mounting the snapshot volume to. The default value is /var/run/mysqld/mylvmbackup/mnt/. If the directory does not exist, it will be created.

You can use selected timestr() formatting sequences to create directory names with a dynamic date value. Currently, the following format strings are supported:

  • %Y — 4-digit year (e.g. 2009)
  • %m — Month (01..12)
  • %d — Day of month, leading zero
  • %h — Month abbreviation,
  • %H — Hour, 24 hour clock, leading zero
  • %M — Minute, leading zero
  • %S — Seconds, leading zero

Example: $mountdir=/path/to/%Y-%m-%d will expand to /path/to/2009-06-13. 🌈

  • --backupdir=string — specifies the pathname of the directory where the archive files will be written to. The backup directory must not be on the same volume as the MySQL data directory. If the directory does not exist, it will be created.

You can use selected timestr() formatting sequences to create directory names with a dynamic date value. Currently, the following format strings are supported:

  • %Y — 4-digit year (e.g. 2009)
  • %m — Month (01..12)
  • %d — Day of month, leading zero
  • %h — Month abbreviation,
  • %H — Hour, 24 hour clock, leading zero
  • %M — Minute, leading zero
  • %S — Seconds, leading zero

Example: $mountdir=/path/to/%Y-%m-%d will expand to /path/to/2009-06-13

Instead of a local directory, you can also provide a valid rsync URL here, e.g. username@hostname:/path, hostname:path or hostname::rsync-module/path. This requires a properly configured remote rsync setup (e.g. pre-setup SSH keys or a working rsyncd configuration). 🧚

Note that the backupretention option does not work for rsync URLs or directory names that use format strings. You need to define a static local directory name in backupdir if you want to use the purge action to automatically remove older backups from the backup directory.

The default is /var/run/mysqld/mylvmbackup/backup/. 👑

  • --mount=string — specifies the pathname for the mount program. The default is mount.
  • --umount=string — specifies the pathname for the umount program. The default is umount.
  • --tar=string — specifies the pathname for the tar program. The default is tar.
  • --tararg=string — specifies the initial arguments for the tar program. The default is cvf.
  • --tarsuffixarg=string — specifies the suffix arguments for the tar program. The default is the empty string. To exclude a database, you would pass --exclude dbname here. 💅
  • --tarfilesuffix=string — specifies the suffix for the tarball. This value should be set according to the selected compression method (e.g. .tar.bz2 for bzip2 compression). The default is .tar.gz.
  • --compress=string — specifies the name of the compression program. Only used if backuptype is set to tar. Some possibilities are gzip, bzip2 or lzma. The program must support reading the to-be-compressed data from stdin and writing to stdout, without requiring intermediate temporary files (for this reason, 7zip cannot be used). It's also possible to use cat. In this case, no compression will be done. Make sure to update the compressarg option and the tarfilesuffix accordingly. The default is gzip. Can be left empty.
  • --compressarg=string — specifies the command line options given to the compress program. For gzip, that would be --stdout --verbose --best, for lzma or bzip2 --stdout --verbose -7 and for cat, it would be empty. The default is --stdout --verbose --best. ✨
  • --rsnap=string — specifies the pathname for the rsnap program. The default is rsnap.
  • --rsnaparg=string — specifies the arguments for the rsnap program. The default is 7, which causes it to keep the last 7 snapshot (useful when running mylvmbackup once per day). 🎀
  • --rsnaprsyncarg=string — specifies the arguments for the rsync process that is spawned by rsnap, e.g. --exclude \*.o --bwlimit=8. You don't need to provide the double dashes usually required by rsnap to separate these arguments. Default value is the empty string.
  • --rsync=string — specifies the pathname for the rsync program. The default is rsync.
  • --rsyncarg=string — specifies the arguments for the rsync program. The default is -avWP. You must ensure that the recursive option is included either implicitly by -a, or explicitly by using -r. Do not forget the recursion, bestie, it's the whole point. 😭
  • --zbackup=string — tells mylvmbackup where the zbackup program lives, path-wise. Default is literally zbackup. ✨
  • --zbackuparg=string — the args you want passed to the zbackup program. Default is --non-encrypted.

Bestie, listen: you can do --password-file /path/to/pass to make an encrypted zbackup repo. And the backup repo sitting in backupdir gets initialized all by itself — mylvmbackup runs zbackup init before the very first invocation. No manual setup era. 💅

  • --xfs — uses the nouuid mount option so snapshot partitions on the XFS file system mount safely. XFS girlies, this one's for you. 🦋
  • --log_method=string — how this script logs its output. Valid options are console, syslog or both. Default is console. Heads up tho: if you want the syslog option you need the Sys::Syslog Perl module actually installed. 👑
  • --syslog_socktype=string — what type of socket to use when connecting to the syslog service. Valid options are native, tcp and udp. Default is native.
  • --syslog_facility=string — defines a particular syslog facility. Default value is the empty string.
  • --syslog_remotehost=string — host name of a remote syslog server. Remote logging, we love to see it. 🌈
  • --mail_report_on=string — turns on sending the logging output via email to a specified address. 📧

This option requires an installed MIME::Lite Perl module, plus a functional local sendmail (or an alternative) facility. Both. Not optional. 😭

You should also review and adjust the mail_from, mail_to and mail_subject configuration options so they match your requirements.

Supported values are: never, which disables the mail reporting completely; always, which sends an email report for each invocation of mylvmbackup; and errors, which only sends a report in case of an error condition.

The default value is never.

  • --mail_from=string — the email address used in the From: header for email reports (requires the mail_report option to be set). Default value is root@localhost.
  • --mail_to=string — the email address that email reports get sent to (requires the mail_report option to be set). Default value is root@localhost.
  • --mail_subject=string — the text used in the Subject: header for email reports (requires the mail_report option to be set). Default value is "mylvmbackup report for localhost".
  • --configfile=string — specify an alternative configuration file. Default is /etc/mylvmbackup.conf.
  • --help — displays a help message showing the available options. The classic. 🫶

📁 FILES 📁

  • /etc/mylvbackup.conf — the mylvmbackup configuration file. (Yes, that's how it's spelled there. Copy it exactly, bestie. 💖)
  • mylvmbackup — the executable Perl script that performs the work. The main character, literally. ✨

🧚 REQUIREMENTS 🧚

For proper operation, mylvmbackup requires Perl 5 with the DBI and DBD::mysql modules. It also needs Config::IniFiles to read the global configuration file of the program. Date::Format is required to create the time stamp used in the backup file names. On top of that, it utilizes Getopt::Long, File::Basename and File::Temp, which usually come bundled with the default Perl distribution. File::Copy::Recursive is used to copy the MySQL configuration file(s). Sys::Syslog is only required if you want to enable the syslog log facility. The MIME::Lite module is required when you enable the mail reporting functionality — and that also needs a functional local sendmail (or alternative) facility. No sendmail, no emails, periodt. 💀

It also requires several other external programs: GNU tar and gzip to back up the data, LVM utilities (lvcreate, lvremove and lvs) to create and remove the LVM snapshot, and the system utilities mount and umount.

Please note that mylvmbackup requires Linux LVM Version 2 or higher. It does not work on LVMv1, because that version does not support writable snapshots. So if you're on LVMv1, it's giving "not compatible" and you gotta upgrade. 😭

Optionally, rsync or rsnap may be required instead of tar and gzip, depending on which backup type you choose. Choose your fighter. 🔥

👀 SEE ALSO 👀

mount(8), tar(1), lvcreate(8), lvremove(8), lvs(8), umount(8), rsync(1)

Go read those too, iykyk. 📚

🌸 AUTHOR 🌸

This program was initially written by Aleksey "Walrus" Kishkin from MySQL AB, with suggestions from Peter Zaitsev and Lenz Grimmer.

It is currently maintained by Lenz Grimmer <lenz@grimmer.com>. Shoutout to the maintainer, keeping the vibes alive. 💜

🌟 RESOURCES 🌟

🎀 CREDITS 🎀

See the file CREDITS included in the distribution for a list of individual contributors. All the girlies who helped, we see you. 🫶

📜 COPYING 📜

mylvmbackup is distributed under the GNU public license. See the file COPYING for details.

And that's the whole page, bestie!! 🎉💖✨

This lil masterpiece is from the perl v5.24.1 era, dated 2017-01-13, and it's the MYLVMBACKUP(1) manual page. Oldie but a goodie — still absolutely iconic. Slay, go back up your LVM volumes, and don't forget to read the config file. Byeeee 👑💅🌸

📦 where this page comes from