reset_sdp.command_summary.txt #11

USAGE for reset_sdp.sh v3.2.0:

reset_sdp.sh [-B|-local] [-fast] [-no_ssl] [-no_sd] [-c <cfg>] {[-b <branch>[,@cl] | -t <tarfile>]} [-p <dir1>[,<dir2>,...]>] [-i <helix_installer_branch>] [-D] [-X]

or

reset_sdp.sh -C > reset_sdp.cfg

or

reset_sdp.sh [-h|-man]


SAFETY NOTICE:
	This script SHOULD NEVER EXIST on a Production Perforce server.

DESCRIPTION:
	This script simplifies the process of testing an SDP installation,
	repetitively blasting all process by the 'perforce' user and resetting
	the SDP from the ground up, blasting typical SDP folders each time.

	It installs the Perforce Helix Core server (P4D) with a P4Broker,
	and installs the Perforce Sample Depot data set used for training
	and PoC installations.

	It is helpful when bootstrapping a demo server with a sample data
	set, complete with broker, and optionally Perl/P4Perl and
	Python/P4Python.

	This script handles all aspects of installation. It does the
	following:
	* Creates the perforce OS user, if needed.
	* Creates the home directory for the perforce user, if needed.
	* Adds OS packages as needed for P4Perl/P4Python local builds.

	Following installation, it also does the following to be more
	convenient for demos, and also give a more production-like feel:
	* Grants the perforce user sudo access.
	* Creates default ~perforce/.bash_profile and .bashrc files.
	* Connects to the Perforce Package Repository (APT and YUM only).

PLATFORM SUPPORT:
	This works on Red Hat Enterprise Linux, CentOS, and Mac OSX
	10.10+ thru Mojave platforms.  It works on RHEL/CentOS
	6.4-7.6, SuSE Linux 12, and likely on Ubuntu 18 and other Linux
	distros with little or no modification.

	This script currently supports the bin.linux26x86_64 (Linux) and
	bin.maxosx1010x86_64 (Mac OSX/Darwin) architectures.

	This script recognizes SysV, Systemd, and Launchd init mechanisms,
	though does not currently support Launchd on OSX.

	For Mac OSX, note that this requires bash 4.x, and the default
	bash on Mac OSX remains 3.x as of OSX Mojave.  For operating on
	Mac, the /bin/bash shebang line needs to be adjusted to reference
	a bash 4 version, e.g. /usr/local/bin/bash if installed with
	Homebrew.

REQUIREMENTS:
	Development utilities such as 'make', the 'gcc' compiler,
	and 'curl' must be installed and available in the PATH (unless
	running with '-fast'), or accessible from the OS package manager.

	The following OS packages are installed (unless '-fast' is
	used):

	* Yum: curl gcc gcc-c++ make openssl openssl-devel rsync wget zlib zlib-devel

	* AptGet: build-essential libssl-dev make zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev

	* Zypper: curl gcc gcc-c++ make openssl openssl-devel wget zlib zlib-devel

OPTIONS:
 -c <cfg>
	Specify a config file.  By default, values for various settings
	such as the email to send script logs to are configure with
	demo values, e.g. P4AdminList@p4demo.com.  Optionally, you can
	specify a config file to define your own values.

	For details on what settings you can define in this way, run:
	reset_sdp.sh -C > reset_sdp.cfg

	Then modify the generated config file as desired.  The generated
	config file contains documentation on settings and values.  If
	no changes are made to the generated file, running with
	'-c reset_sdp.cfg' is the equivalent of running without
	using '-c' at all.

 -C	See '-c <cfg>' above.

 -B	Specify '-B' to blast base SDP dirs, for a clean start.

	Otherwise without '-B', downloaded components from earlier
	runs will be used (which should be fine if they were run
	recently).

	The '-B' flag also replaces files in the /hxdepots/reset
	directory, where this script lives, with those downloaded
	from The Workshop (the versions of which are affected
	by the '-i <helix_installer_branch>' flag, described
	below).

	The '-B' flag also blasts the /tmp/downloads and /tmp/p4perl
	directories, used by install_sdp_python.sh and
	install_sdp_perl.sh, if they exist.

	The '-B' and '-local' arguments are mutually exclusive.

 -local
	By default, various files and executables are downloaded from
	the Perforce Workshop or the Perforce FTP server as needed.
	With '-local', any missing files are treated as an error
	condition.

	The '-B' and '-local' arguments are mutually exclusive.

 -fast	Specify '-fast' to skip installation SDP Perl and
	SDP Python, to include P4Perl and P4Python.

	The '-fast' argument changes a check for GCC/G++
	from a fatal error to a warning message.

	The '-fast' option typically takes just a few minutes,
	as compared to 20+ minutes without due to the time
	needed to compile and test the Perl and Python bits.

	The '-fast' flag should not be used if you plan to
	deploy or develop triggers that use P4Python or P4Perl,
	such as the SDP CheckCaseTrigger.py.  Alternately, you
	can run with '-fast', and then afterward run the
	following as the OS user perforce:

	cd /hxdepots/sdp/Server/Unix/setup
	./install_sdp_python.sh
	./install_sdp_perl.sh

 -no_ssl
	By default, the Perforce server is setup SSL-enabled.  Specify
	'-no_ssl' to avoid using SSL feature.

 -no_sd
	By default, the Perforce Sample Depot data set is loaded.
	Specify '-no_sd' to skip loading the Sample Depot.

 -p <dir1>[,<dir2>,...]>]
	Specify a comma-delimited list of directories under /p4/common
	to preserve that would otherwise be removed.  Directories must
	be specified as paths relative to /p4/common, and cannot contain
	spaces.

	For example, the value '-p config,bin/triggers' would preserve the
	/p4/common/config and /p4/common/bin/triggers directories.

	Directories specified are moved aside to a temporary working area
	before the SDP folders are removed.  After installation, they are
	moved back via an 'rsync' command with no '--delete' option.  This
	means any files that overlap with the stock install are replaced
	by ones that originally existed, but non-overlapping files are not
	removed.

	This is intended to be useful for developing test suites that
	install server under /p4/common/bin, e.g. Component Based Development
	scripts which install under /p4/common/bin/cbd would use '-p bin/cbd'.

 -b <branch>[,@cl]
	The default SDP install method is to clone the SDP from the main
	branch in The Workshop (public.perforce.com:1666).  Specify '-b' to use
	a different branch, e.g. 'dev'.

	If '-b' is specified with the optional @cl syntax, where @cl
	specifies a changelist with files shelved on the given branch,
	a form of unshelving is done, enabling a workflow for testing
	shelved changes with the Helix Installer.  So for example,
	specify '-b dev,@23123' to clone from the dev branch, and then
	followed by a fetch of shelved changelist @23123, which is
	expected to have files shelved in the dev branch.

 -t <tarfile>
	Specify a tarfile to use, e.g. '-t sdp.Unix.2017.3.23041.tgz', or
	use the special value '-t default' to use the default SDP tarfile,
	sdp.Unix.2019.1.25320.tgz

	The specified tar file must exist here:
	https://swarm.workshop.perforce.com/projects/perforce-software-sdp/files/downloads

	If '-t <tarfile>' is not specified, default install method is
	used instead, which is to clone the SDP main branch from The
	Workshop (public.perforce.com:1666).

	Use '-t' to get a known version of the SDP for testing.  Avoid '-t'
	to test with the very latest SDP from a given branch (see '-b' above
	for more info), even if the latest has not yet been packaged into a
	distribution tar file.

DEBUGGING OPTIONS:
 -i	<helix_installer_branch>

	Specify the branch of the Helix Installer to use.  This affects the
	URL from which Helix Installer files in /hxdepots/reset are pulled from
	The Workshop.  The default is main; an alternative is '-i dev'.

 -D     Set extreme debugging verbosity.

 -X	Extreme reset. This removes the user accout for perforce and
	blast all SDP-related directories at the start of script operations,
	including the perforce home directory.

	Using '-X' does not blast the Helix Installer downloads or exes
	directories, and thus is compatible with either the'-B' or '-local'
	options.

HELP OPTIONS:
 -h	Display short help message
 -man	Display man-style help message

EXAMPLES:
	=== FAST INSTALLATION (skipping Perl, Python) ===

	su -
    	mkdir -p /hxdepots/reset
	cd /hxdepots/reset
	curl -k -s -O https://swarm.workshop.perforce.com/download/guest/perforce_software/helix-installer/main/src/reset_sdp.sh
	curl -k -s -O https://swarm.workshop.perforce.com/download/guest/perforce_software/helix-installer/main/src/r
	chmod +x reset_sdp.sh r
	./r

	Note that the 'r' wrapper script calls the reset_sdp.sh script with
	a pre-defined of flags optimized for fast opreration.  The 'r' wapper
	also handles log capture, writing to the file 'reset_sdp.log'.

	=== COMPREHENSIVE INSTALLATION ===

	su -
    	mkdir -p /hxdepots/reset
	cd /hxdepots/reset
	curl -k -s -O https://swarm.workshop.perforce.com/download/guest/perforce_software/helix-installer/main/src/reset_sdp.sh

	chmod +x reset_sdp.sh
	./reset_sdp.sh 2>&1 | tee reset_sdp.log

	=== CONFIGURED INSTALLATION ===

	su -
    	mkdir -p /hxdepots/reset
	cd /hxdepots/reset
	curl -k -s -O https://swarm.workshop.perforce.com/download/guest/perforce_software/helix-installer/main/src/reset_sdp.sh
	chmod +x reset_sdp.sh

 	### Generate a default config file:
	./reset_sdp.sh -C > reset_sdp.cfg

 	### Edit reset_sdp.cfg, changing the values as desired:
	vi reset_sdp.cfg

	./reset_sdp.sh -c reset_sdp.cfg 2>&1 | tee reset_sdp.log

	=== SDP DEV BRANCH TESTING ===

	The Helix Installer can be used to test SDP changes shelved to the SDP
	dev branch in The Workshop.  The following example illustrates testing
	a change in shelved changelist 23123:

	su -
    	mkdir -p /hxdepots/reset
	cd /hxdepots/reset
	curl -k -s -O https://swarm.workshop.perforce.com/download/guest/perforce_software/helix-installer/main/src/reset_sdp.sh

	./reset_sdp.sh -b dev,@23123 2>&1 | tee reset_sdp.CL23123.log

	After the first test, an iterative test cycle may follow on the same
	shelved changelist. For each test iteration, the shelved changelist
	is first updated in the workspace from which the change was originally
	shelved, e.g. with a command like 'p4 shelve -f -c 23123'.

	Then a new test can be done by calling reset_sdp.sh with the same
	arguments. The script will re-install the SDP cleanly, and then
	re-apply the updated shelved changelist.