opt_perforce_sdp_backup.sh.man.txt #1

USAGE for opt_perforce_sdp_backup.sh v2.8.2:

opt_perforce_sdp_backup.sh [-d|-D]

or

opt_perforce_sdp_backup.sh [-h|-man|-V]


DESCRIPTION:
	This script is intended to called by a systemd timer on systems
	that support systemd.

	There is an opt_perforce_sdp_backup.service for this; it can be
	reviewed by doing:
	
	$ systemctl cat opt_perforce_sdp_backup.service

	This service is triggered by a systemd timer, which can be viewed by:
	$ systemctl cat opt_perforce_sdp_backup.timer

	If operating on a system without systemd, then it is OK to call this
	directly, e.g. via crontab. It must execute as root.

	This script backups key P4 Server Deployment Package (SDP) files and
	directories.  It does not back up actual P4 Server application data.
	The job of this script is to ensure any SDP files that are stored on
	the local OS root volume are backed up a data volume that is backed up.
	If no data volume is found, an extra copy of files is made on the OS
	root volume.

BACKUP LOCATION

	This script determines the optimal backup location based on the server
	type being backed up.  Some sample locations for backup are:

	P4 Server: /hxdepots/backup/opt_perforce_helix-sdp.<ShortHostname>
	P4 Proxy:  /hxdepots/backup/opt_perforce_helix-sdp.<ShortHostname>
	P4 Broker: /hxlogs/backup/opt_perforce_helix-sdp.<ShortHostname>

GENERATED RECOVERY SCRIPT

	Each time a successful backup completes, this script creates a
	recovery script.  The recovery script is generated each time to
	ensure that site-specific settings such as SDP instances names
	and mount point locations are accounted for.  This ensures that
	the recovery faithfully places files in the original structure.

	The generated recovery script is in the backup directory and is
	named: recover_opt_perforce_sdp.sh

	During each backup in which the generated recovery script changes,
	diffs from the prior recovery script are displayed, and the old
	recovery script is backed up in the backup location by moving it
	aside to a '.bak.<timestamp>' suffix, and the active file is
	updated.  It is expected that this backup script will change
	infrequently, e.g. when new SDP instances are added (or removed),
	and possibly in future SDP version changes. In any case, the new
	script will update and replace the old.

	This does whatever is needed to restore SDP as it was at the time
	of backup, including:
	* Creates the group of the SDP Owner if needed.
	* Creates the SDP Owner user if needed.
	* Restores the SDP Owner home directory if needed.
	* Restores the SDP Owner crontab.
	* Restores all SDP files and symlinks that exist outside the
	data volumes (e.g. /hxdepots, /hxlogs, /hxmetadata[1,2]).

	It does NOT restore operating system package installations.

RECOVERY PROCEDURE

	The recovery procedure is to cd to the backup location, operating
	as root, and run the script as in this example:

	cd /hxdepots/backup/opt_perforce_helix-sdp.<ShortHostname>
	./recover_opt_perforce_sdp.sh

OTHER FILES TO RESTORE - HOME DIRECTORY

	This does NOT backup files in the '' user home directory, as this
	is expected to be backed up by other means and/or per local policy,
	and is outside the scope of this script.

	The home directory may include files that affect server operation, and
	thus should be recovered before using script. Some files to be recovered
	are:
	* ~/.bash_profile
	* ~/.bashrc
	* ~/.p4aliases.

	Templates for these can be found in /p4/sdp/Server/Unix/setup/bash.

	The home directory may also include an ~/.ssh directory and ~/.config
	and similar directories.

OPTIONS:
 -L <log>
	Specify the path to a log file, or the special value 'off' to disable
	logging.  By default, all output (stdout and stderr) goes to a log file
	pointed to by a symlink:

	opt_perforce_sdp_backup

	The symlink is for convenience. It refers to the log from the most recent
	run of the script.

	Each time this script is run, a new timestamped log is started, and
	the symlink updated to reference the new/latest log during startup.  Log
	files have timestamps that go to the second (or millisecond if needed)
	to differentiate logs.

	NOTE: This script is self-logging.  Output displayed on the screen is
	simultaneously captured in the log file. Using redirection operators like
	'> log' or '2>&1' are unnecessary, as is using 'tee' (though using 'tee'
	or redirects is safe and harmless).

 -d
	Display debug messages.

 -D
	Set extreme debugging verbosity using bash 'set -x' mode. Implies -d.

 -si
	Silent Mode.  No output is displayed to the terminal (except for usage errors
	on startup). Output is captured in the log.  The '-si' cannot be used with
	'-L off'.

HELP OPTIONS:
 -h	Display short help message.
 -man	Display man-style help message.
 -V	Display script name and version.

FILES:
	/etc/systemd/system/opt_perforce_sdp_backup.service
	/etc/systemd/system/opt_perforce_sdp_backup.timer

TO DO:
	A future version of this script may preserve the crontab of the OSUSER.