hms_ts_setup.command_summary.txt #1

USAGE for hms_ts_setup.sh v2.3.1:

hms_ts_setup.sh [-y] [-d <sdp_dir>] [-s] [-L <log>] [-v<n>] [-n] [-D]

or

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


DESCRIPTION:
	The HMS "tight ship" setup script transforms a standard SDP
	installation into a tight-ship style installation on the master
	server machine.

	A tight ship installation is one in which:
	* The key SDP folders, e.g. /p4/common and /p4/N/bin (for
	each instance) are versioned locally using SDP.<hostname>
	workspaces in a local HMS instance, /p4/hms, which this script
	creates and initializes.

	* The crontab for the Perforce user is versioned.

	* Any local configuration and/or customizations of the SDP
	are versioned.

	* The HMS instance is aware of The Workshop, a public
	Helix server hosted by Perforce Software.  It fetches SDP
	updates from The Workshop into the local hms instance using
	Helix DVCS features.

	This simplifies future updates of the SDP, allowing them
	to be done with a 'p4 fetch' followed by a 'p4 merge'
	on your local server (if the server can reach The
	Workshop directly; if not an alternative
	approach using an interim personal repo can be used to
	bridge 'air gap' networks).

PRE-REQUISITES:
	The following are pre-requisites to running hms_ts_setup.sh:

	1. The SDP configuration script, mkdirs.cfg must have been
	configured, and mkdirs.sh must have been run.

	The SDP is expected to exist in /hxdepots/sdp (or whatever
	diretory is specified with '-d <sdp_dir>').  This may have
	been populated via a tar file or workspace pulling files from
	The Workshop (P4PORT=workshop.perforce.com:1666),
	pulling files from //guest/perforce_software/sdp/main on that
	server.

	The /hxdepots/sdp/Server/Unix/setup/mkdirs.cfg must already be
	configured correctly, and mkdirs.sh must have been run for at
	least one instance.  The password stored in the newest of the
	/p4/common/config/.p4passwd.*.p4admin files will be used
	for the perforce user for the hms instance.

	2. The /p4/common/config/sdp_hosts.cfg file is configured to
	reference only this current master server machine.  If this
	file does not exist, a template can be copied from
	/hxdepots/sdp/Server/Unix/p4/common/config/sdp_hosts.cfg.

	3. Perforce crontab initialized.

	The crontab for the perforce user must already be configured as
	intended.

	4. No cruft symlinks in /p4.

	In the /p4 directory, and /p4/<N> symlinks which contain a
	/p4/<N>/root/server.id file are considered to be valid SDP
	instances.  This script will attempt to manage any such files.

	5. No hms instance.

	There should not (yet) be an hms instance.

	6. Determine if sudo access is available.  If The OSUSER
	(typically 'perforce') has full sudo privs, then HMS can
	go further in the management of things; e.g. it can
	manage Swarm (which requires root access).

	Specify the '-s' option on the command line if the OSUSER is
	be able to execute 'sudo su' commands without a password.  This
	can be accomplished on modern Linux systems by creating
	/etc/sudoers.d/perforce, with this one line of contents:

	perforce  ALL=(ALL:ALL) NOPASSWD: ALL

	If configured properly, the following command should execute
	without error:
	sudo /bin/ls /etc/sudoers.d

ADDITIONAL SETUP:
	The following setup is necessary before operating in a tight
	ship environment, but are not necessary before running this
	script.

	1. The SSH keys must be configured enabling the 'perforce' user
	to ssh without a password to all machines listed in sdp_hosts.cfg
	configured above, including the current host (i.e. it must be
	able to ssh to itself using the current hostname).

OPTIONS:
 -y	Continue past the preflight without an interactive prompt.

 -d <sdp_dir>
	Specify the root of the directory tree where the SDP package
	is available.  The default is: /hxdepots/sdp

	The version of the SDP installed must be recent enough to
	contain the 'hms' setup directory:
	/hxdepots/sdp/Server/Unix/setup/hms.

 -s	Specify '-s' if sudo access is available.  If sudo access
	is available, HMS can manage more things than it can without
	sudo access, e.g. Swarm.

	Adding '-s' adds a preflight check to verify sudo access.

 -v<n>	Set verbosity 1-5 (-v1 = quiet, -v5 = highest).

 -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:
	..

	NOTE: This script is self-logging.  That is, output displayed on the screen
	is simultaneously captured in the log file.  Do not run this script with
	redirection operators like '> log' or '2>&1', and do not use 'tee.'

 -n	No-Op.  Prints commands instead of running them.

 -D     Set extreme debugging verbosity.

HELP OPTIONS:
 -h	Display short help message
 -man	Display man-style help message
 -V	Dispay version info for this script and its libraries.

FILES:

EXAMPLES:
	This is best done immediately after a standard SDP
	installation, and must be run on the same master server
	machine where the SDP was installed.

SEE ALSO: