ccheck.sh.man.txt #12

USAGE for ccheck.sh v2.3.0:

ccheck.sh [<SDPInstance>] [-p <Profile>] [-fix|-FIX] [-sec [-no_ssl]] [-p4config /path/to/.p4config] [-c <CfgFile>] [-y] [-v] [-d|-D]

or

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


DESCRIPTION:
	This script compares configurables set on the current server with best
	practices.  When used to check for security best practices, use the
	'-sec' option.

	The best practices are defined in a data file.  The default data file
	provided is:

	/p4/common/config/configurables.cfg

	Optionally, if the '-fix' or '-FIX' options are used, this script can make
	changes to p4d, via 'p4 configure' commands, to bring it in line with best
	practices.  A preview of proposed changes is then displayed.  The '-y'
	option can then be used to proceed with the operation.

	This script is currently intended to run only on a commit server.  It
	may be updated in the future to provide further information for replica and
	edge servers.

OPTIONS:
 -p <Profile>
 	Specify a profile defined in the config file, such as 'demo' or 'hcc'.  A profile
	defines a set of expected configurable values that can differ from the expected
	values in other profiles.  For example, for a demo environment, the filesys.P4ROOT.min
	might have an expected value of 128M, while the expected value in a prod (production)
	profile might be 5G, and the same value might be 30G for 'prodent', the profile for
	production at large enterprise scale.

	The 'always' profile defines settings that always apply whether '-p' is specified
	or not. The profile specified with '-p' applies in addition to the 'always'
	configuration, adding to and possibly overriding settings from the 'always'
	configuration.

	The default profile is 'prod', the production profile.

	Specify the special value '-p none' to use only the settings defined in the
	'always' profile.

 -sec	Specify '-sec' to do a focused security check.

	This option also adds one additional check to ensure that the P4PORT value
	used is SSL-enabled (unless '-no_ssl' is specified).

 -no_ssl
	Specify '-no_ssl' with '-sec' to bypass the check for an SSL-enabled P4PORT.

 -p4config <P4CONFIG_File>
	Specify the path to a P4CONFIG file containing P4PORT, P4USER, P4TICKETS,
	and P4TRUST settings to connect as a super user to any P4 Server.

	This can be used with '-sec' on an SDP-managed server to check security
	settings of a non-SDP server.

	If the server targeted by the P4CONFIG settings is a non-SDP server the '-sec'
	option is not used, expect some errors related to not following best practices,
	some of which may be SDP-specific.

	Before using '-p4config' with this script, first create and test your P4CONFIG
	file using the 'p4' command line client with the '-E' option to exercise the
	settings.

	Start by creating the P4CONFIG file in /p4/common/site/config, a good location
	for site-local config files.

        mkdir -p /p4/common/site/config
	echo P4PORT=ssl:OtherServer:1666 > /p4/common/site/config/.p4config.OtherServer
	echo P4USER=bruno >> /p4/common/site/config/.p4config.OtherServer
	echo P4TICKETS=/p4/common/site/config/.p4tickets.OtherServer >> /p4/common/site/config/.p4config.OtherServer
	echo P4TRUST=/p4/common/site/config/.p4trust.OtherServer >> /p4/common/site/config/.p4config.OtherServer

	Next, establish trust (unless the other server is not SSL-enabled):

	p4 -E P4CONFIG=/p4/common/site/config/.p4config.OtherServer trust -y

 	Then login (which may require SSO authenticaiton if your other server is thusly
	configured):

	p4 -E P4CONFIG=/p4/common/site/config/.p4config.OtherServer login

	Ensure you are a super on the other server, and that Protections on the
	other server allows you to connect from your current machine.  You
	may need to modify Protections on the other server to get this to work:

	p4 -E P4CONFIG=/p4/common/site/config/.p4config.OtherServer protects -m

	Then give it a try, e.g.:

	ccheck.sh -sec -p4config /p4/common/site/config/.p4config.OtherServer

 -c <CfgFile>
	Specify an alternate config file to define best practice configurables. This
	is intended primarily for testing. It can also be useful to define a site-local
	definition of best practices to compare against.  To use this option, first
	copy the default file to create a local copy in the /p4/common/site/config,
	e.g.
	
	cp -p /p4/common/config /p4/common/site/config/configurables.cfg

	Then reference it with '-c /p4/common/site/config/configurables.cfg'.

	WARNING: If you maintain a site-local copy of configurables.cfg, you will
	need to keep it current after SDP upgrades by manually merging in changes
	from the latest SDP version delivered with each release. Thus, using this
	option is discouraged.

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

	$LOGS/ccheck.log

	The symlink is for convenience. It refers to the log from the most recent
	run where '-L' was not used.

	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.  That is, 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).

 -fix	Specify -fix to take corrective action to resolve differences between
	current settings and the recommended/required values.  Optional settings
	are not affected by '-fix', only those indicated as Recommended or
	Required.

	When -fix is specified, this script determines on a per configurable basis
	whether it is safe to proceed immediately with the advised change, or if
	should be deferred until potentially disruptive impacts are understood.
	This determination is made based on the configuration file, which provides
	links go guidance documentation for configurables that are best changed
	with awareness of potential impact.  Such changes are displayed with '-fix',
	but require use of '-FIX' to process.

	As an example and a special case, the 'security' configurable will be
	changed to 4 with '-fix' if the starting value is 3, because that is deemed
	a low-risk change.  Changing the 'security' value to 4 if the starting
	value is 0-2 requires -FIX, as that is more likely to be impactful to
	users, and thus is best done with coordinated communications.

	In any case, if the security configurable is to be modified, additional
	guidance is provided regarding the potential impact to other p4d servers that
	access this server using the remote depot feature. Such access via the remote
	depot feature will cease to function when security is set to 4.

	This option previews advised changes by default. Use with -y to make changes.

 -FIX	Specify -FIX to make all changes that have been automated, even those that
	'-fix' would refuse to process immediately.

	In some cases even with -FIX, there may be follow up work to do. Follow up
	tasks will be indicated with 'TO DO:' comments in the output.

	The '-FIX' option implies '-fix'.

	This option previews advised changes by default. Use with -y to make changes.

 -y	Live operation mode.  By default, any commands that affect data, such as
	setting configurables, are displayed, but not executed.  With the '-y' option,
	commands may be executed.

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

GENERAL ADVICE and DISCLAIMER:
	This script is based on a data file that represents generalized best
	practices. This data file should be considered a source of information
	to be checked against other sources, such as the System Administration
	Guide and/or documentation on specific configurables found here:

	https://help.perforce.com/helix-core/server-apps/cmdref/current/Content/CmdRef/configurables.alphabetical.html

	Before acting on information provided by the script, and especially before
	using the '-fix' and '-FIX' options, be sure to review the output carefully.

	Contact Perforce Technical Support for guidance as needed.

EXAMPLES:
	Example 1: Basic Check, No Logging

	Check configurables with the default profile ('prod' for a commercial
	production server) and no logging:

	ccheck.sh -L off

	Example 2: Alternate Profile

	Check configurables with the 'pub' profile (for a public/open source server):

	ccheck.sh -p pub

	Example 3: Verbose comparison

	Check configurables with the 'demo' profile, doing a verbose comparison:

	ccheck.sh -p demo -v

	Example 4: Security focused check

	Use the '-sec' option to report only security-related settings:

	ccheck.sh -sec

	Example 5: Security focused check with fixes

	To do a security focused check making only non-disruptive fixes, use
	'-fix', and start with a preview by omitting the '-y' option:

	ccheck.sh -sec -fix

	If the output is correct, append the '-y' to the command to make changes:

	ccheck.sh -sec -fix -y

	Example 6:

	To do a security focused check, including potentially disruptive fixes,
	use '-FIX', and start with a preview by omitting the '-y' option:

	ccheck.sh -sec -FIX

	Be sure to review the output carefully and read about potential impacts.
	Some configurables, such as 'auth.id'. require planning to change. For
	those configurables that require planning, additional guidance is
	provided if the script advises those settings be changed.  Read and heed
	the guidance.

	In the case of 'auth.id' specifically, this script will call 'p4login -v',
	'p4 login -service', and 'p4login -v -automation' if that configurable is
	set, account for the need to login again after setting 'auth.id'.  The
	script also displays a warning indicating that those commands should also
	be run manually on any other server machines in the fleet.

	If the output is correct, append the '-y' to the command to make changes:

	ccheck.sh -sec -FIX -y

FUTURE ENHANCEMENTS:
	* Add multi-version support for backward compatibility. This version assumes
	  P4D 2024.2+ (though it may be useful for older versions).

FILES:
	The default configurables config file is: /p4/common/config/configurables.cfg

	This file contains further documentation on the format of entries in
	the file.