diff --git a/README.md b/README.md index 1267c6c..ac588d4 100644 --- a/README.md +++ b/README.md @@ -1,261 +1,267 @@ # Micro Backup script This is a keep it simple and stupid backup script. ## Installation Choose a directory and then clone this repository: ``` git clone REPOSITORY_URL ``` Please change the URL to point on your own fork (if you have one). Example for me: ``` git clone https://gitpull.it/source/micro-backup-script/ ``` ## Configuration Enter in the cloned directory and run: ``` cp backup-instructions-example.conf backup-instructions.conf cp options-example.conf options.conf ``` Then edit these files with your favorite text editor: * `options.conf` * `backup-instructions.conf` ## Options documentation (`options.conf`) The file `options.conf` is designed to store important options (like `BOX` and `BASE`). The file `options.conf` can be copied from the example called `options-example.conf`. ### Option `BOX` The `BOX` option sets the human name for your local computer. Default: current `hostname`. The `BOX` option is recommended in order to be independent from the hostname and have more stable backup pathnames. The `BOX` option is used to create a directory with the same name. Here 3 examples: ``` BOX=gargantua BOX=my-local-nice-machine BOX=server001.example.com ``` NOTE: The `BOX` option is used to build the final pathname of your on-site backups. See below. ### Option `BASE` The `BASE` option sets the base pathname for on-site backups. Default: `/home/backups` for historical reasons. The `BASE` option is strongly suggested in order to be independent from the system default. The `BASE` option should **not** end with a slash. The `BASE` option should contain a valid filesystem pathname. Here 3 examples: ``` BASE=/var/backups/stark-industries BASE=/mnt/stark-industries BASE=/tmp/test-backups ``` For example if you set `BASE=/var/backups/stark-industries` and `BOX=gargantua`, your on-site backups will be placed in `/var/backups/stark-industries/gargantua`. ### Option `PORCELAIN` -The option `PORCELAIN` allows to debug everything and do nothing to just see what would be done without executing any command. +The option `PORCELAIN` allows to debug everything and do nothing. It's useful to see what would be done without executing any command. The option `PORCELAIN` accepts an empty value (default) or `1`. When `1` the flag is activated. Here 2 examples: ``` # run all instructions normally (default) PORCELAIN= # do not run any instruction but just print them PORCELAIN=1 ``` +The option `PORCELAIN` will skip the following actions when set to `1`: + +* skip any database dump (avoiding to run `mysqldump`) +* skip any data transfer via rsync (adding a `--dry-run') +* skip any systemd stop/start command + ### Option `NO_DISSERVICE` The option `NO_DISSERVICE` is a flag that can avoid any command related to a systemd service. It's disabled as default. The option `NO_DISSERVICE` is only useful if you use some backup instructions related to systemd and you want to debug them. The option `NO_DISSERVICE` accepts an empty value (default) or `1`. When `1` the flag is activated. Here 2 examples: ``` # run all systemd-related instructions normally (default) NO_DISSERVICE= # do not run any systemd-related instruction NO_DISSERVICE=1 ``` ## Instructions documentation (`backup-instructions.conf`) The file `backup-instructions.conf` contains the backup commands (which databases should be saved, which pathnames, etc.) The file `backup-instructions.conf` can be copied from an example called `backup-instructions-example.conf`. ### Instruction `backup_path` The instruction `backup_path` instruction does an on-site copy of a directory or a single file. Examples: ``` # save the Unix configuration files backup_path /etc # save all user homes backup_path /home # save a copy of this specific log file backup_path /mnt/something/log.err ``` The data will be saved in a sub-directory of `$BASE/$BOX/daily/files` keeping the original structure. For example the path `/mnt/something/log.err` will be stored under `$BASE/$BOX/daily/files/mnt/something/log.err`. ### Instruction `backup_paths` The instruction `backup_paths` (note it ends with an "s") allows to save multiple pathnames or use Bash globs to capture multiple pathnames. Example: ``` # backup only the log files who start with "Kern" backup_paths /var/log/Kern* # backup these pathnames backup_paths /home/mario /home/wario ``` ### Instruction `backup_last_log_lines` The instruction `backup_last_log_lines` saves the last lines of a long txt file. Example: ``` backup_last_log_lines /var/log/secure ``` ### Instruction `backup_database` The instruction `backup_database` runs a `mysqldump` on a specific database and compress it with `gzip`. The instruction `backup_database` saves the database under `$BASE/$BOX/daily/databases/$DATABASE_NAME.sql.gzip`. Examples: ``` # first, backup a database with a specific name backup_database wordpress_testing # then, backup another database backup_database wordpress_production ``` ### Instruction `backup_every_database` The instruction `backup_every_database` runs a `mysqldump` for every database (but not on the skipped ones). The instruction `backup_every_database` skips as default `information_schema` and `performance_schema` and more databases can be ignored using the instruction `skip_database`. Example: ``` # skip 2 databases skip_database "^BIG_DATABASE_PRODUCTION_ALPHA$" skip_database "^BIG_DATABASE_PRODUCTION_BETA$" # backup all the others backup_every_database ``` ### Instruction `skip_database` The instruction `skip_database` adds another database name from the exclusion list of `backup_every_database`. The instruction `skip_database` accepts only one argument expressed as a regular expression and has no effect if it's executed after `backup_every_database` or without a `backup_every_database` in your instructions. Examples: ``` # skip this specific database skip_database "^BIG_DATABASE_PRODUCTION_ALPHA$" # skip also all databases starting with the prefix 'OLD_' skip_database "$OLD_.*$" # backup all the remaining databases backup_every_database ``` ### Instruction `backup_service_and_database` The instruction `backup_service_and_database` can be used to stop a service, backup its database, and restart the service. The instruction `backup_service_and_database` does not try to stop a not-running service and does not try to start it if it was not running. If it's not running it just backups the expressed database. Example: ``` backup_service_and_database tomcat9.service WEBAPPDB ``` ### Instruction `backup_phabricator` The instruction `backup_phabricator` puts a Phabricator installation in maintenance mode, then it dumps all its databases, and then it removes maintenance mode. Examples: ``` backup_phabricator /var/www/phabricator DATABASEPREFIX_ ``` ### Instruction `push_path_host` The instruction `push_path_host` sends local files (e.g. `/home/foo`) to a remote host (e.g. `example.com`). Example: ``` push_path_host /home/foo backupuser@example.com:/var/backups/remote-destination ``` The instruction `push_path_host` works running an `rsync` command and connecting to SSH to the remote host. So your local Unix user will to run `ssh backupuser@example.com`. So, if it does not work, and if you have no idea how SSH works, just run these and press enter 10 times from your local Unix user: ``` ssh-keygen ssh-copy-id backupuser@example.com ``` If it still does not work and you don't know how to configure SSH or how to use rsync, trust me, RTMF about SSH and rsync. ### Instruction `push_daily_directory` The instruction `push_daily_directory` sends your local daily backup to a remote host (e.g. `example.com`). Example: ``` push_daily_directory backupuser@example.com:/var/backups/remote-destination ``` The instruction `push_daily_directory` internally uses the `push_path_host` passing the pathname `$BASE/$BOX/daily` as first argument. ## Usage After you configured `options.conf` and `backup-instructions.conf`, there are no arguments. Just run this: ``` ./backup-everything.sh ``` You have to run that command from the crontab. ## License 2020, 2021, 2022 ER Informatica, Valerio Bozzolan MIT License https://mit-license.org/ ## Contact For EVERY question, feel free to contact Valerio Bozzolan: https://boz.reyboz.it