MYSQL-ZRM-BACKUP(1)

📦 version 3.0, in epel 9, fedora 43, fedora 44

mysql-zrm-backup(1) 💖

okay so bestie, pull up a chair, because <pink>mysql-zrm-backup</pink> is the whole entire manual page for the backup utility that ships with ZRM for MySQL, and I'm about to walk you through it like we're texting at 2am. no cap. every flag, every default, every warning — all of it, but make it ✨fun✨.

NAME 🎀

mysql-zrm-backup — the Backup utility for ZRM for MySQL. that's it, that's the name, she's simple and she's iconic.

SYNOPSIS 🌸

here's the vibe, the general shape of the thing:

mysql-zrm-backup
                [--backup-set name]
                [Backup Source Options]
                [MySQL Access Options]
                [Backup Method Options]
                [Backup Destination Options]
                [Logging and Notification Options]
                [--options-file conf_file]
                [--help]

Backup Source Synopsis 🦋

mysql-zrm-backup
            [--all-databases]   |   [--databases "dbname1 dbname2"...] |
            [--database "name" [--tables tname1 tname2 ...]]
[--exclude-pattern pattern]
            [--routines | --no-routines]
            [--mysql-binpath MySQL_command_dir]
            [--mysql-binlog-path MySQL_binary_log_dir]
            [--config-file-list="config_file_pathname"]

MySQL Access Synopsis 🔑

mysql-zrm-backup
                      [--user user]
                      [--password password]
                      [--host hostname]
                      [--port portnumber]
                      [--socket name]
                      [--ssl-options "MySQL ssl options"]
                      [--single-transaction [always|never|only-innodb]]
                      [--extra-mysqldump-options mysqldump_options]
                      [--extra-mydumper-options mydumper_options]

Compression and Encryption Synopsis 🗜️

mysql-zrm-backup
                 [--compress | --no-compress]
                 [--compress-mysqldump-onthefly | --no-compress-mysql-
dump-onthefly]
                 [--compress-plugin plugin_name]
                 [--no-encrypt | --encrypt]
                 [--encrypt-plugin plugin_name [--decrypt-option
option]]
                 [--passfile filename]

Plugin Synopsis 🧚

mysql-zrm-backup
                 [--pre-backup-plugin plugin]
                 [--pre-backup-plugin-options "option1 option2 ..."]
                 [--copy-plugin plugin]
                 [--ssh-user user]
                 [--ssh-identity-file filename]
                 [--remote-mysql-binpath path]
                 [--socket-remote-port port]
                 [--post-backup-plugin plugin]
                 [--post-backup-plugin-options "option1 option2 ..."]

Backup Method Synopsis 🎯

mysql-zrm-backup
   [--backup-level level]
   [--backup-mode raw | logical]
   [--logical-parallel 0 | 1]
   [--synchronous-checksum | --no-synchronous-checksum]
   [--replication | --noreplication]
   [--retention-policy backup_retention_time]
   [--default-character-set char_set_name]
   [--compress-data-during-transport]

Snapshot Plugin Synopsis 📸

mysql-zrm-backup
   [--snapshot-plugin="snapshot_plugin_pathname"]
   [--check-innodb | --no-check-innodb]
   [--backup-type regular|--backup-type quick]

   --snapshot-plugin=""/usr/share/mysql-zrm/plugins/lvm-snapshot.pl"
                    [--snapshot-size size]

   --snapshot-plugin="/usr/share/mysql-zrm/plugins/zfs-snapshot.pl"
                    (no options necessary)

Backup Destination Synopsis 📦

mysql-zrm-backup
                       [--backup-name image_name]
                       [--destination dir_path]
                       [--tmpdir temp_dir

Logging and Notification Synopsis 📬

mysql-zrm-backup
                       [--mailto address]
                       [--mail-policy always|never|only-on-error]
                       [--comment "comment string"]
                       [--quiet|--no-quiet]
                       [--verbose]

DESCRIPTION 💜

so ZRM for MySQL gives you automated scheduling of live MySQL database backup. the whole thing is: you configure it one time to match your MySQL deployment, and then you just schedule it and let it run unattended backups while you go live your life. 🫶

and there's a whole pile of options that help an administrator:

  • verify the backups that got created.
  • generate all kinds of reports about the backups that got created.
  • specify compression and encryption however you want them.
  • report information about the backups via an email or an RSS feed.
  • access pre- and post-backup plugins to extend the suite even further.
  • control full and selective restore operations on the database, both locally and remotely.

mysql-zrm-backup is the one serving the core backup functions of ZRM for MySQL databases. main character energy, honestly.

use the mysql-zrm.conf(5) configuration file to set mysql-zrm-backup options that are described on this page. and use the --action check option to verify the configuration of mysql-zrm-backup. 💅

use mysql-zrm-backup to create full or incremental backups of MySQL databases.

want help on individual action options? just append the --help option to the command line. like, for example:

'mysql-zrm-backup --options-file --help'

BACKUP SETS 🗂️

ZRM for MySQL organizes backups into Backup Sets. every backup set defines the list of databases or tables within a database, how it should be backed up, and the backup schedule for that data. each backup set gets identified by a unique name. no duplicates, bestie, we don't do that here.

every single backup run — meaning every time mysql-zrm is executed — is associated with one backup set. and various parameters can be associated with each backup run.

here's the order of operations, listen up: mysql-zrm first reads the global configuration file at /etc/mysql-zrm/mysql-zrm.conf. that global config can be overridden by a backup-set-specific configuration file stored in the /etc/mysql-zrm/backup set name directory. and then the mysql-zrm command line options override the parameters specified in the configuration files. so it's like: global < backup set < command line. the command line always wins. periodt. 👑

BACKUP METHODS 🔥

mysql-zrm backups can be either full or incremental. and full backups can be logical backups or raw backups.

  • Logical backups contain SQL statements to recreate the database.
  • Raw backups are actual copies of the database files.

when a logical backup is specified, the utility uses only mysqldump for backing up the specified databases and tables.

when a raw backup is specified, the utility gets to decide which backup mechanism to use for a particular database. if there are no transactional-storage-engine-based tables in the specified database, then it uses mysqlhotcopy for backing up that database. otherwise, it uses mysqldump for backing up the specified database. she's flexible like that. 💁‍♀️

Snapshot backups get their own moment in the Snapshot Options section of this man page — go look there, bestie.

when replication is specified and the MySQL server is a replication slave, then it will also back up all the replication-related files. no files left behind. 🦋

when a destination is specified, then the backups are stored in a subdirectory under the specified directory. the default path is /var/lib/mysql-zrm. ⚠️ and listen: if the destination you specified does not exist, it will return an error and exit — the utility does not create the directory for you. you gotta make it yourself. the audacity, I know.

an index file also gets created in the backup directory. the index is a file that contains the details of what was backed up, how much data was backed up, what parameters were used to back up the data, how much time it took to back up, etc. receipts, basically. 🧾

when an incremental backup is specified, the following options are ignored:

  • backup-mode,
  • snapshot-plugin,
  • all-databases,
  • databases,
  • database
  • tables

OPTIONS ✨💅

you can select a backup set by name on the command line, or you can select source database(s), backup methods, plugins, etc. by using the options described in the Options subsections that follow. you can also specify mysql-zrm-backup options in a configuration file specified using the --options switch. choose your own adventure, babe. 🌈

  • --backup-set name — specify the backup-set for the backup run. this is a command line option only and it cannot be specified in the configuration file. the default value is BackupSet1, and if such a value is already present, it will be used.
  • --options-file conf_file — set the file, along with the full pathname, that contains mysql-zrm-backup configuration options. this file has the same format as mysql-zrm.conf(5).
  • --help — displays the help message and exits. this is a command-line-only parameter and it cannot be specified in the configuration file.

Backup Source Options 🌸

  • --all-databases — opt for all databases to be backed up or restored. this is the default if database or databases are not specified. she's the fallback queen. 👑
  • --databases "name1 name2 ..." — list the databases to back up or restore.
  • --database name [--tables "name1 name2 ..."] — list the tables that should be backed up. this option is valid during the backup operation only. note it, bestie.
  • --exclude-pattern "pattern" — all databases or tables that match the pattern are not backed up. if --all-databases or --databases are specified, the exclude pattern applies to database names. if --database is specified, the exclude pattern applies to table names. wildcard characters are supported:
    • * — match one or more characters
    • ? — match one character
    • [] — match one of the characters specified within parenthesis
    • | — match one of the patterns

for example: the exclude pattern "*_db|dbase[123]|abcd" will match names tom_db, dbase1, dbase2, abcd. all tables or databases that match this pattern will be excluded.

⚠️ the character # is not permitted in the exclude pattern. just don't, okay?
  • --routines|--no-routines — if --routines is specified, then mysqldump will dump stored routines. the default is --no-routines. this parameter is optional.
  • --mysql-binpath mysql_command_dir — set the full path where the mysql binary commands are installed. for example: /opt/lampp/bin. 📁
  • --mysql-binlog-path mysql_binary_log_location — set the full path of the location of the mysql binary logs. for example: /var/log/mysql.
  • --config-file-list="list_file_path" — intended for configuration file backup, this optional parameter lets you specify a list of files to backup during…

a full backup of literally any type — snapshot, logical, raw, all of it 💅. The list_file_path is just the path to the file that holds the list of configuration files you wanna back up. And that list itself has to spell out full pathnames, separated by newlines. No shortcuts, bestie.

The config-file-list gets processed after the main data has already been backed up, and the list file itself gets copied over to the destination directory right along with the configuration files. The backup index will record the config-file-list parameter. 📝

And the slay part: files you named in config-file-list get re-stored during a full restore to their original locations, with permissions and ownership preserved. 🫶

🌸 MySQL Access Options 🌸

  • --user user — Says who the MySQL backup/restore user is on the MySQL server. If you don't specify a user here, just make sure the MySQL user you set up in the my.cnf or --options file actually has the privileges it needs. Otherwise, chaos. 💀
  • --password password — The password for that MySQL user. If you do not want your password getting yeeted across the network in plaintext, maybe set the MySQL username and password in the MySQL my.cnf or --options file instead. Just a thought. 🙈
  • --host hostname — Specify the MySQL server host name or IP name.
  • --port portnumber — Specify the MySQL server port.
  • --socket name — Specify which socket file to use when talking to the MySQL server.
  • --ssl-options "MySQL ssl options" — Set any --ssl* options that MySQL supports. Peep the MySQL Documentation if you want the deets on SSL options.
  • --single-transaction [always|never|only-innodb] — This one controls under what circumstances MySQL for ZRM passes the --single-transaction option setting to mysqldump when it runs a database dump. always means --single-transaction is always passed, never means it's never passed, and only-innodb means it's only passed during innodb-only backups. For example, if you say only-innodb, the --single-transaction will not be passed for backups that include myisam or other non-transactional tables. ikyk. 👑
  • --extra-mysqldump-options="mysqldump_options" — Use this to pass any extra mysqldump options when ZRM for MySQL runs a mysqldump. For example, if you need mysqldump to run with the --flush-logs and --no-create-info options, specify --extra-mysqldump-options="--flush-logs --no-create-info" in the mysql-zrm.conf file.
  • --extra-mydumper-options="mydumper_options" — Use this to pass any extra mydumper options when ZRM for MySQL runs a mydumper. For example, if you need mydumper to run with the --threads and --regex options, specify --extra-mydumper-options="--threads=4 --regex='Regular expression for 'db.table' matching'" in the mysql-zrm.conf file.

🔥 Backup Method Options 🔥

  • --backup-level level — Choose 0 for a full backup. Choose 1 for an incremental back up. Default is full backup. Simple as that. ✨
  • --backup-mode raw|logical — Databases/tables that use a transactional engine cannot be backed up by mysqldump — those need mysqlhotcopy. So: choose raw to use mysqlhotcopy to back up the database/tables that use a transactional engine, and choose logical to use mysqldump to back up the database/tables that don't use a transactional engine. Default value is raw. 🌈
  • --logical-parallel |1 — Choose 0 for a mysqldump backup. Choose 1 for a mydumper multi-thread logical back up. Default is mysqldump backup.
  • --synchronous-checksum | --no-synchronous-checksum — Says whether a checksum should be produced during the backup process. Default is --no-synchronous-checksum, in which case the checksum is produced only after the backup process is complete. Heads up: specifying --synchronous-checksum significantly increases overall backup times. Not a vibe if you're in a hurry. 😭
  • --replication | --noreplication — Choose replication to back up replication files. They'll only get backed up if the host is a replication slave. Default option is --noreplication.
  • --default-character-set char_set_name — The default character set that mysqldump should use. If it's not specified, utf8 is used. This parameter is optional.
  • --compress-data-during-transport — If the value is set to 1, the backup gets compressed when it's transferred from the MySQL server to the ZRM server. Set the value to zero and no compression happens. No compression is performed by default. And fyi: data compression during transfer is independent of the Backup compression parameter. 🧚

💜 Plugin Options 💜

  • --pre-backup-plugin plugin — (Optional) Specify the plugin, along with its full pathname, to be called before a backup run. Every pre-backup plugin script has to accept these command-line parameters (which get passed to the plugin using --pre-backup-plugin-options:
    • --all-databases — Use when all databases on the server are being backed up.
    • --database database1 database2... — Use when selected databases are being backed up.
    • --database database --tables table1 table2... — Use if selected tables are being backed up.

The script should be written to return a non-zero value on error; pre-backup plugin failures should cancel the backup and generate a failure message for reports and logs. No quiet fails, periodt. 🚫

  • --pre-backup-plugin-options "option1 option2..." — Pass options to the pre-backup-plugin as one of the command line arguments.
  • --copy-plugin plugin — Specify the plugin, along with full pathname, to be used for transferring backup files to and from a remote MySQL server to the machine running ZRM for MySQL. Use this option when:
    1. remote incremental backup is required
    2. copying replication related files from a remote machine
    3. execute mysqlhotcopy (MySQL command) and copy the data from the remote machine
    4. restore data to a remote machine using mysqlhotcopy (MySQL command).

This parameter is optional.

  • --ssh-user user — Specifies the user to be used for SSH. This parameter is only used by the ssh-copy.pl plugin. The user you pick should either be the user mysqld runs as, or root. If you don't specify one, the default value used is mysql. This parameter is optional.
  • --ssh-identify-file filename — Selects a file from which the identity (private key) for RSA or DSA authentication is read. This identity file is used by the ssh-copy.pl plugin for authentication. 🔐
  • --remote-mysql-binpath path — Full path where the mysql binaries are installed on the remote machine. For example: /opt/lampp/bin. This parameter is only used by the socket-copy.pl and ssh-copy.pl plugins. If not specified, the default value used is /usr/bin.
  • --socket-remote-port port — The port that the socket-plugin.pl should use to connect. This parameter is only used by the socket-copy.pl plugin. If not specified, the default value used is 25300. This parameter is optional.
  • --post-backup-plugin plugin — Set the plugin, along with full pathname, to be called after a backup run. If synchronous-checksum is not set, or its value is set to zero, the post backup plugin gets called twice — once at the end of backup, and once when the checksum is finished. Twice the drama, twice the fun. 💅
  • --post-backup-plugin-options "Option1 Option2 Option3 Option4..." — option1 is the value of post-backup-plugin-options from the mysql-zrm.conf(5) file. option2 is the data being backed up. It will be either:
    • --all-databases — Use when all databases on the server are being backed up.
    • --database database1 database2... — Use when selected databases are being backed up.
    • --database database --tables table1 table2... — Use if selected tables are being backed up.

Option3 will be --backup-directory path.

Option4 will be --checksum-pending or it will be --checksum-finished if synchronous-checksum is set to 1.

If synchronous-checksum is not set or its value is set to zero, the post-backup-plugin is called again and it will have 3 parameters. First parameter is the value of post-backup-plugin-options from the mysql-zrm.conf(5) configuration file. Second parameter will be --backup-directory path. Third parameter will be --checksum-finished.

🎀 Compression and Encryption Options 🎀

  • --compress | --no-compress — Choose whether the files should be compressed using the utility specified by the --compress-plugin. The default is --no-compress.
  • --compress-mysqldump-onthefly | --no-compress-mysqldump-onthefly — Choose whether to compress the data dumped by mysqldump on the fly. Default compression command used is gzip. Default is no compression on the fly.
  • --compress-plugin plugin_name — Use plugin_name to specify a path to the utility to use for compression. The default is gzip.
  • --no-encrypt | --encrypt — Choose whether the files should be encrypted using the utility specified by the --encrypt-plugin. The default is --no-encrypt.
  • --encrypt-plugin plugin_name [--decrypt-option [option] — Use plugin_name to specify a utility to use for compression, along with its full path. If --decrypt-option is

...if that thing isn't specified, then the -d option of encrypt-plugin is the one that gets used for decrypting. periodt. 💜

  • --passfile filename — okay so the original literally just drops the option name here and gives you nothing else, bestie. No description, no nothing. I'm not about to invent one for you, so: here it is, exactly as written. 🙈

✨ Snapshot Plugin Options ✨

  • --snapshot-plugin="plugin_pathname" — tells ZRM which plugin handles your snapshot operations. The default? The lvm-snapshot plugin. Slay. 🧚
  • [--check-innodb | --no-check-innodb] — this one decides whether we go looking for innodb shared data and log files to back up during every single snapshot-based backup (the original says "based based" and honestly? iconic typo behavior 💀). Here's the vibe check:
    • if you pass --check-innodb, innodb shared data and logs only get backed up if the databases you're backing up actually use innodb.
    • if you pass --no-check-innodb (which is the default), those innodb databases and logs get backed up regardless of whether they're relevant at all. The default value is --no-check-innodb, which means innodb shared data and logs are always copied if the innodb engine is enabled in MySQL. In most cases, --no-check-innodb gives you the best performance. 🏎️
  • --snapshot-size size — sets the size of the lvm-snapshot that's gonna be generated. For raw backups, every specified database gets checked first to make sure it's on a LVM volume, and then a snapshot of the size you named gets created and used to back up the database. If the database you specified is not on a LVM volume, then either mysqlhotcopy or mysqldump gets used to create the backup, based on whatever logic the --backup-mode option laid out. Also important: this option gets ignored if the --backup-mode is logical. 🙅‍♀️
  • --backup-type regular|--backup-type quick — pick your snapshot backup method, bestie.
    • regular means the snapshot gets copied into a standard ZRM for MySQL backup archive.
    • quick means the snapshot itself becomes a near-line backup. Quick backups are convenient because they give you near-instantaneous restores, but because they stay sitting on the MySQL server, they do not protect you against media or server failure. 😭
⚠️ Heads up: if the quick option is specified, the compress and encrypt options are ignored, and the backup size will always be zero. On top of that, no checksums are performed, which means quick snapshot backups cannot be verified. Not the move if you care about integrity, ngl.

✨ Backup Destination Options ✨

  • --backup-name image_name — give your backup a unique name to be stored under. If you don't specify a name, or if it already exists in the --destination dirpath (peep the next option), the backup image gets named with the current date and time instead. ⏰
  • --destination dir_path — where your backup lives. Default location is /var/lib/mysql-zrm/. If you pick a directory that isn't the default, you have to create it manually on both the MySQL server and the ZRM server, and it must have permissions set to allow read/write access to the mysql backup user. 🫶

✨ Logging and Notification Options ✨

  • --mailto address — set the address where a backup report gets sent. 📧
  • --mail-policy always|never|only-on-error — mail policy = when do emails actually fire off? Here's the breakdown:
    • always is the default — email notification is sent for all events.
    • never — email notification is not sent for all events.
    • only-on-error — notification is sent when there's a backup failure, if mailto is specified.
  • --comment "Comment string" — drop a comment or a note about the backup run. You can use this to tag backup runs, and you can retrieve that note later with the mysql-zrm-reporter(1) utility. 🏷️
  • --quiet | --no-quiet — quiet suppresses the display of log messages on stdout. no-quiet shows those log messages on stdout. Default is --no-quiet. 🤫
  • --verbose — gives you verbose output in the log. Default is that verbose is turned off and a terse output is generated. ✨

📁 FILES 📁

  • /var/lib/mysql-zrm — default directory for storing all backup data. 💾
  • /etc/mysql-zrm/backup set name/mysql-zrm.conf — default location for the backup-set configuration file used by the mysql-zrm-backup utility. 🎀

🚦 RETURN VALUES 🚦

On success, zero is returned. On error, a non-zero value is returned. Simple as that, bestie. 💅

👀 SEE ALSO 👀

👑 AUTHOR 👑

Zmanda Inc. (http://www.zmanda.com)

and that's the whole page, bestie!! 🌈✨ This cutie came out of the ZRM for MySQL manual, page mysql-zrm-backup(1), brought to you by Zmanda, Inc. (no date on this chunk, sorry — nothing to report there 💀). Now go back up your databases responsibly. mwah. 💖🦋🎀

📦 where this page comes from