install_sdp.sh.man.txt #1

USAGE for install_sdp.sh v5.0.0:

To Install a Helix Core P4D Server (with optional broker):

install_sdp.sh {-init|-empty|-sampledepot} [-demo] [-c <cfg>] [-no_cron] [-no_ppr] [-no_systemd|-no_enable] [-no_firewall] [-no_sudo|{-limited_sudo|-full_sudo}] [-v] [-no_pkgs|-extra_pkgs] [-s <ServerID>] [-si <SDPInstance>] [-ts <TargetServerID>] [-se] [-H <hostname>] [-T <timezone>] [-local] [-sdp_dir <sdp_dir>] [-d|-D]

To Install a standalone Helix Proxy:

install_sdp.sh -t p4p [-c <cfg>] [{-empty|-sampledepot}] [-no_cron] [-no_ppr] [-no_systemd|-no_enable] [-no_firewall] [-no_sudo|-limited_sudo|-full_sudo] [-v] [-no_pkgs|-extra_pkgs] [-s <ServerID>] [-si <SDPInstance>] [-ts <TargetServerID>] [-tp <TargetPort>] [-lp <ListenPort>] [-se] [-H <hostname>] [-T <timezone>] [-local] [-sdp_dir <sdp_dir>] [-d|-D]

To Install a standalone Helix Broker:

install_sdp.sh -t p4broker [-c <cfg>] [{-empty|-sampledepot}] [-no_cron] [-no_ppr] [-no_systemd|-no_enable] [-no_firewall] [-no_sudo|-limited_sudo|-full_sudo] [-v] [-no_pkgs|-extra_pkgs] [-s <ServerID>] [-si <SDPInstance>] [-ts <TargetServerID>] [-tp <TargetPort>] [-lp <ListenPort>] [-se] [-H <hostname>] [-T <timezone>] [-local] [-sdp_dir <sdp_dir>] [-d|-D]

or

install_sdp.sh -C > sdp_install.cfg

or

install_sdp.sh [-h|-man]


DESCRIPTION:
	This script simplifies the process of installing Perforce Helix with the
	Server Deployment Package (SDP) on a fresh, new server machine.

	If you are adding a new SDP instance to a machine that already has SDP
	installed, use the mkdirs.sh script for that purpose.  See: mkdirs.sh -man

	If you are unsure if SDP is installed, see if there is a /p4 directory
	on the machine. If that directory exists, then SDP is already installed,
	and this install_sdp.sh script will refuse to operate on the machine.

	This script is intended only for initial installation on a new server
	machine. For safety, it will refuse to operate if it detects any existing
	SDP directory structures. If installed on a machine where Helix Core
	data exists in non-SDP structures, it will not interact with the existing
	data.  SDP structures include anything in or under the following
	directories:

	* /p4
	* /opt/perforce/helix-sdp/p4/sdp
	* /hx{checkpoints,depots,logs,metadata*}

	This script can be used to install any of the following:
	* A Helix Core Server (p4d commit, standby, edge, etc.) with an optional p4broker.
	* A standalone Helix Broker (p4broker).
	* A standalone Helix Proxy (p4p).

	If installing a Helix Core Server, there are three options, one of which
	must be specified:
	* Use '-init' to initialize a new data set using the configure_new_server.sh script to get
	started with various best practices. This is the default behavior.
	* Use '-empty' to
	* Use '-sampledepot' to install the Sample Depot training data set.  This is helpful when
	  bootstrapping a training or demo server.

	The following SDP structure is initialized:
	/opt/perforce/helix-sdp/sdp (root owned, immutable except by SDP upgrades).
	/opt/perforce/helix-sdp/p4/sdp (owned and writable by OSUSER).
	/opt/perforce/helix-sdp/downloads (owned and writable by OSUSER).
	/opt/perforce/helix-sdp/p4/sdp/helix_binaries (owned and writable by OSUSER).

	This script handles many aspects of installation. It does the
	following:
	* Creates the operating system user (OSUSER) that Helix Core
	  processes (p4d, p4broker, and/p4 p4p) will run as.  The
	  default OSUSER is 'perforce'.  The 'useradd' command is
	  used to create the user as a local account on the machine,
	  and a password.  OSUSER creation and password setting is
	  skipped if that account already exsits.  If a non-local
	  network account is to be used, that must be created
	  first before running this script.
	* Creates the home directory for the OSUSER user, if needed.

	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 (full or limited).
	* Creates default ~perforce/.bash_profile and .bashrc files.
	* Connects to the Perforce Package Repository (APT and YUM only).
	* Installs SDP crontab for the perforce OSUSER.

	This script calls mkdirs.sh for additional configuration:
	* Systemd service files are enabled (or SysV on older systems).
	* Firewall ports are opened for installed services.

PLATFORM SUPPORT:
   This script is intended to work any version of UNIX, Linux, or
   Mac OSX (Darwin) on which Helix Core software operates. However, the
   following are prioritzed for support:

   * Red Hat Enterprise Linux (RHEL) / Rocky Linux 9
   * Ubuntu 22.04 and 24.04. (For Ubuntu, only *.04 releases are supported).

	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 Sequoia.  For operating on
	Mac, the /bin/bash shebang line needs to be adjusted to reference
	a bash 4 version, e.g. /opt/homebrew/bin/bash if installed with
	Homebrew. (Generally, production servers run only on Linux; Mac
	support is primarily intended for development and testing).

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

	* Yum: bc cronie curl mailx make openssl openssl-devel rsync sos sysstat tar tuned wget which zlib zlib-devel

	* AptGet: bc cron curl libbz2-dev libncurses5-dev libreadline-dev libsqlite3-dev libssl-dev llvm make rsync sysstat tuned wget zlib1g-dev

	* Zypper: bc cronie curl make openssl openssl-devel rsync sos sysstat tuned wget which zlib zlib-devel

	If '-extra_pkgs' is used, the following packages are installed in
	addition to those listee above:

	* Yum: gcc gcc-c++

	* AptGet: build-essential

	* Zypper: gcc gcc-c++

	Development utilities such as 'make', the 'gcc' compiler,
	and 'curl' will be available '-extra_pkgs' is used.

	In addition, if the Perforce Package Repository is added,
	these additional packages are installed:

	* Yum: perforce-p4python3

	* AptGet: perforce-p4python3

	* Zypper: None, as the Perforce Package Repository does
	not support the Zypper package management system (e.g.
	as used on SuSE Linux).

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:
	install_sdp.sh -C > setings.cfg

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

 -C	See '-c <cfg>' above.
 
 -init
	Specify '-init' to initialize a new Helix Core data set with the
	configure_new_server.sh script, which applies best practices for a
	production server installation.

	One of '-empty', '-init', or '-sampledepot' must be specified.

 -empty
	Specify '-empty' to avoid initializtion of a Helix Core data set.  No
	db.* files will be created.

	This option should be used if you intend to load a checkpoint
	created elsewhere on this new server machine, as would be done
	if you are installing a replica or edge server.

	One of '-empty', '-init', or '-sampledepot' must be specified.

 -sampledepot
	Specify '-sampledepot' to load the Perforce Sample Depot training/demo
	data set.

	One of '-empty', '-init', or '-sampledepot' must be specified.

 -demo
 	By default, key SDP storage volumes are verifed to not appear on
	on the OS root volume. If this is not the case, errors are given in
	preflight checks, and processing aborts.  Specify '-demo' to bypass
	these safety checks.

	This option should NOT be used for production installations.

 -no_cron
	Skip initialization of the crontab.  A crontab file is generated
	in the /p4 directory, but is not loaded as the active
	crontab.

 -no_ppr
	Skip addition of the Perforce Package Repository for YUM/APT
	repos.  By default, the Package Repository is added.

	Specifying '-local' implies '-no_ppr'.

 -no_sudo
	Specify that no updates to sudoers are to be made.

	WARNING: If systemd/systemctl is used to manage Perforce
	Helix services, the OSUSER that operates these services
	('perforce' by default) requires sufficient sudo access to
	start and stop services using systemctl. Using '-no_sudo'
	may result in a unusable service being created if used
	on a system where the systemctl command is available.

	If this option is used, consider also using '-no_systemd'
	to avoid the requiring systemd.  Using systemd is
	recommended where availalbe.

	It is appropriate to use this option if the machine it
	operates on was based on a machine image that already
	grants the OSUSER sufficient sudo accces.

	This option is mutually exclusive with '-limited_sudo' and '-full_sudo'.

 -limited_sudo
	Specify that limited sudo access for the OSUSER created
	is to be granted.  See 'gen_sudoers.sh -man' for details.

	This option is mutually exclusive with '-no_sudo' and '-full_sudo'.

	This option is recommended for optimal security.

 -full_sudo
 	Specify that full sudo access for the OSUSER created
	is to be granted.  See 'gen_sudoers.sh -man' for details.

	This option is mutually exclusive with '-no_sudo' and '-limited_sudo'.

 -v
 	Specify '-v' to run the verify_sdp.sh script after the SDP
	installation is complete. If '-v' is specified and the
	verify_sdp.sh script is available in the SDP, it is executed.

	If the Sample Depot is loaded with '-sampledepot' or a new server was
	initialized with '-init', the '-online' flag to the verify_sdp.sh
	script is added.  If '-no_cron' is specified, the corresponding
	'-skip cron' option is added verify_sdp.sh.  If '-empty' is
	specified, the '-skip' tests also exclude the offline_db and
	p4t_files checks in verify_sdp.sh.

 -no_pkgs
	Specify '-no_pkgs' to skip OS package installation using
	the package manager (yum, apt-get, or zypper).

	WARNING: Using this option may cause the initail install
	and/or subsequent operation to fail, and this using
	this is not advised.
 
-extra_pkgs
	Specify '-extra_pkgs' to install additional OS packages
	as may be needed for development of systems integrations,
	custom triggers, etc.  See package lists above for
	more detail.

 -local
	By default, various files and binaries are downloaded from
	the Perforce Workshop and the Perforce FTP server as needed.

	If the server machine on which this install_sdp.sh is to be
	run cannot reach the public internet or if using files from
	external sites is not desired, the '-local' flag can be used.

	With '-local', needed files must be acquired and put in place
	on the server machine on which this script is to be run.  Any
	missing files result in error messages and an aborted install.

	Specifying '-local' implies '-no_ppr'.

	For '-local' to work, the following must exist:

	1. Helix Binaries
	
	Helix binaries must exist in /opt/perforce/helix-sdp/p4/sdp/helix_binaries:

	* /opt/perforce/helix-sdp/p4/sdp/helix_binaries/p4
	* /opt/perforce/helix-sdp/p4/sdp/helix_binaries/p4d
	* /opt/perforce/helix-sdp/p4/sdp/helix_binaries/p4broker
	* /opt/perforce/helix-sdp/p4/sdp/helix_binaries/p4p

	2. Server Deployment Package (SDP)

	The SDP tarball must be acquired an put in place here:

	* /opt/perforce/helix-sdp/downloads/sdp.Unix.tgz

	It can be acquired on a machine that can reach the internet with this command:

	curl -L -O https://swarm.workshop.perforce.com/download/guest/perforce_software/sdp/downloads/sdp.Unix.tgz

	3. Sample Depot Tarball
	
	The Sample Depot appropriate to your platform must exist if the
	'-sampledepot' option is used:

	* /opt/perforce/helix-sdp/downloads/sampledepot.mac.tar.gz (on Mac/OSX if case-insensitive)
	* /opt/perforce/helix-sdp/downloads/sampledepot.tar.gz (on UNIX/Linux or case-sensitive Mac)

	See EXAMPLES below for a sample of acquiring files for use with
	'-local' mode.

 -no_firewall
	Specify '-no_firewall' to skip updates to firewall.

	By default, if on a system for which the host-local firewall
	service (firewalld or ufw) is available and running when this
	script is called, then the firewall service is updated to open
	appropriate ports for the Perforce Helix services installed.

 -no_systemd
	Specify '-no_systemd' to avoid using systemd, even if it
	appears to be available. By default, systemd is used if it
	appears to be available.

	This is helpful in operating in containerized test environments
	where systemd is not available.

	This option is implied if the systemctl command is not available
	in the PATH of the root user.

	This option is mutually exclusive with '-no_enable'.

 -no_enable
	Specify '-no_enable' to avoid enabling systemd services that
	are installed and enabled by default. Specifically, this means
	that the call to 'systemctl enable' for installed services is
	skipped.

	This option is mutually exclusive with '-no_systemd'.

 -t <ServerType>
 
 	Specify the type of server. Valid values are:

	* p4d_master - A p4d master/commit server.
	* p4d_replica - A p4d replica with all metadata from the master (not
	  filtered in any way).
	* p4d_filtered_replica - A p4d filtered replica or filtered forwarding
	  replica.
	* p4d_edge - An p4d edge server.
	* p4d_edge_replica - A p4d replica of a p4d edge server. The TargetServerID
	  must also be set if ServerType is p4d_edge_repica.
	* p4broker - An SDP host running only a Helix Broker.
	* p4p - An SDP host running only a Helix Proxy.
	
 -s <ServerID>
 	Specify the ServerID.  A ServerID is required if the ServerType is
       	any p4d_* type other than p4d_master.

 -si <SDPInstance>
	Specify the SDP Instance name.  The SDP Instance name is incorporated
	into the folder structure of the installed service, with many files
	appearing under '/p4/<SDPInstance>', e.g. /p4/1.

	The default is '1'.

 -ts <TargetServerID>
 	Specify the Target ServerID. Set this only if ServerType is
	p4d_edge_replica. The value is the ServerID of edge server that
	this server is a replica of, and must match the ReplicatingFrom:
	field of the server spec.

 -tp <TargetPort>
 	Specify the target port.  For p4broker and p4p only.

 -lp <ListenPort>
 	Specify the port to listen on.  For p4broker and p4p only.

 -se
 	Specify -se to simulate email. This generates a mail simlator
	script: /p4/common/site/bin/mail

 -H <hostname>
 	Set the hostname.  This is only supported on systems that
	support the 'hostnamectl' command. The hostname is set by
	doing: hostnamectl set-hostname <hostname>

	If the corresponding 'Hostname' setting is defined in the
	configuration file and this '-H <hostname>' flag is used,
	the command line option will override the config file.

 -T <timezone>
 	Set the timezone.  This is only supported on systems that
	support the 'timedatectl' command. The timezone is set by
	doing: timedatectl set-timezone <timezone>

	If the corresponding 'Timezone' setting is defined in the
	configuration file and this '-T <timezone>' flag is used,
	the command line option will override the config file.

DEVELOPMENT OPTIONS:
 -sdp_dir <sdp_dir>
	Specify a directory on the local host containing the SDP to deploy.
	This should not be used for production installs.

	The directory specified by '-sdp_dir' is expected to contain either:
	* an SDP tarball (sdp.Unix.tgz) file, or
	* an already-extracted SDP directory, which must include the SDP
	Version file.

	Use the special value '-sdp_dir default' to use the /sdp directory
	(as per the Docker-based SDP Test Suite environment).

DEBUGGING OPTIONS:
 -d     Enable debug message.
 -D     Enable extreme debugging with bash 'set -x'. Implies '-d'.

HELP OPTIONS:
 -h	Display short help message.
 -man	Display this full manual page.

 --help
	Alias for -man.

EXAMPLES:
	=== Demo Installation - Helix Core Server ===

	sudo su -
    	mkdir -p /root/sdp_install
	cd /root/sdp_install
	curl -L -O https://swarm.workshop.perforce.com/download/guest/perforce_software/sdp/main/Server/Unix/setup/install_sdp.sh
	chmod +x install_sdp.sh
	./install_sdp.sh -sampledepot -demo

	=== Typical Production Helix Core Server Installation - New Commit Server ===

	Following is a sample set of instructions for a typical new server setup.

	STEP 1: Configure storage.

	For a production install, storage must first be configured before this script
	can be run.

	See SDP documentation for guidance on storage configuration. There are a variety of
	options and methods for installing storage.  However accomplished, when storage is
	complete the following, the directories must exist and must have storage mounted
	that is NOT on the OS root volume:

	* /hxdepots
	* /hxmetadata
	* /hxlogs

	These paths are typical, but are configurable. More information is available in
	the install configuration file generatedd below.

	STEP 2: Install this script.

	Install this script in a directory under the root user's home directory with
	these commands:

	$ sudo su -
    	$ mkdir /root/sdp_install
	$ cd /root/sdp_install
	$ curl -L -O https://swarm.workshop.perforce.com/download/guest/perforce_software/sdp/main/Server/Unix/setup/install_sdp.sh
	$ chmod +x install_sdp.sh

 	STEP 3: Generate install conifguration file.

	$ ./install_sdp.sh -C > sdp_install.cfg

	STEP 4: Modify install configuration file.

 	Edit the generated sdp_install.cfg using your preferred text editor, changing the values
	as desired. This file contains various settings with documentation for each setting.

	$ vi sdp_install.cfg

	Once settings are decided, save the file.

	STEP 5: Install SDP (Dry Run).

	Call this script and reference the configuration file, as a dry run/preview:

	$ ./install_sdp.sh -c sdp_install.cfg -init

	Review the generated log of the preview, and address any reported issues.

	STEP 6: Install SDP Live Run

	$ ./install_sdp.sh -c sdp_install.cfg -init -y

	This will install SDP per the per the command line and settings in the install
	configuration file.

	=== Typical Production Helix Core Server Installation - Edge/Replica ===

	When installing SDP on a machine intended to be a standby, replica, or edge
	server, the steps are exactly the same as for setting up a new commit server.

	The content of the generated and then edited sdp_install.cfg file will have different
	values for ServerType and ServerID settings. Ensure the CaseSensitity value matches
	the case of the commit server.  (If the commit server is a Windows server and this
	current server machine is to be a Linux replica of a Windows commit server, the
	Linux server must be setup as case-insensitive.)

	=== Standalone Proxy Installation ===

	STEP 1: Install this script.

	Install this script in a directory under the root user's home directory with
	these commands:

	$ sudo su -
    	$ mkdir /root/sdp_install
	$ cd /root/sdp_install
	$ curl -L -O https://swarm.workshop.perforce.com/download/guest/perforce_software/sdp/main/Server/Unix/setup/install_sdp.sh
	$ chmod +x install_sdp.sh

	STEP 2: Install the proxy.

	Install the proxy, specifying the listen port (ssl:1666 in this example)
	and the target port (ssl:p4d.myco.com:1666).

	$ ./install_sdp.sh -t p4p -lp ssl:1666 -tp ssl:p4d.myco.com:1666

	=== Standalone Broker Installation ===

	The instructions for installing the broker are identical to the instructions
	for installing the proxy, except that '-t p4broker' is used instead of
	'-t p4p'.

	=== Local Helix Core Server Install for Air Gap Networks ===

	The following sample commands illustrate how to acquire the dependencies for
	running with '-local' on a machine that can reach the public internet.  The
	resulting file structure, with paths as shown, must somehow be copied to the
	machine where this install_sdp.sh script is to be run.  This can be used to
	facilitate installation on a machine over an "air gap" network.

	$ sudo su -
	$ mkdir -p /opt/perforce/helix-sdp/p4/sdp/helix_binaries
	$ cd /opt/perforce/helix-sdp/p4/sdp/helix_binaries
	$ curl -L -O https://swarm.workshop.perforce.com/download/guest/perforce_software/sdp/main/helix_binaries/get_helix_binaries.sh
	$ chmod +x get_helix_binaries.sh

	If the latest major version available of Helix Core binaries are desired, do this:
	$ ./get_helix_binaries.sh -sbd .

	Or, if older Helix Core binaries are desired, append the version identifer with '-r rYY.N',
	as in this example to get Helix Core 2023.2 binaries:
	$ ./get_helix_binaries.sh -sbd . -r r23.2

	Next, get the SDP tarball and Sample Depot; the Sample Depot tarball:

	$ mkdir /opt/perforce/helix-sdp/downloads
	$ cd /opt/perforce/helix-sdp/downloads
	$ curl -O https://ftp.perforce.com/perforce/tools/
	$ curl -L -O https://swarm.workshop.perforce.com/download/guest/perforce_software/sdp/downloads/sdp.Unix.tgz

	Lastly, acquire this script:

	$ mkdir /root/install_sdp
	$ cd /root/install_sdp
	$ curl -L -O https://swarm.workshop.perforce.com/download/guest/perforce_software/sdp/main/Server/Unix/setup/install_sdp.sh
	$ chmod +x install_sdp.sh

	These acquired files must then be transferred to the machine where the install
	is to occur, and must appear in the same directory structure.