install_sdp.sh.man.txt #3

USAGE for install_sdp.sh version DEV_REBRAND.31781:

To Install a P4 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}] [-keep_env] [-v] [-no_pkgs|-extra_pkgs] [-s <ServerID>] [-si <SDPInstance>] [-ts <TargetServerID>] [-se] [-H <hostname>] [-T <timezone>] [-local] [-sdp_dir <sdp_dir>] [-sdp_overlay_dir <sdp_overlay_dir>] [-d|-D]

To Install a standalone P4 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] [-keep_env] [-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>] [-sdp_overlay_dir <sdp_overlay_dir>] [-d|-D]

To Install a standalone P4 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] [-keep_env] [-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>] [-sdp_overlay_dir <sdp_overlay_dir>] [-d|-D]

or

install_sdp.sh -C > sdp_install.cfg

or

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


DESCRIPTION:
	This script simplifies the process of installing Perforce P4 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 P4 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/p4-sdp/p4/sdp
	* /p4{checkpoints,depots[-2,N],logs,db[-1,2]}

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

	If installing a P4 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, and create an initial checkpoint.
	* 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:
	* Immutable SDP Dir: /opt/perforce/p4-sdp/sdp (root owned, immutable except by SDP upgrades).
	* Writable SDP Dir:  /opt/perforce/p4-sdp/p4/sdp (owned and writable by OSUSER).
	* Downloads:         /opt/perforce/p4-sdp/downloads (owned and writable by OSUSER), for -local installs.
	* Binaries Dir:      /opt/perforce/p4-sdp/p4/sdp/p4_binaries (owned and writable by OSUSER), for -local installs.

	This script handles many aspects of installation. It does the
	following:
	* Creates the operating system user (OSUSER) that P4 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
	  exists.  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.
	* If ~perforce/.bash_profile and .bashrc files exist, they are
    moved aside (unless -keep_env is used).
	* 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 on a variety of Linux distributions
	and Linux server machines.  The following are prioritized for support:

	* Ubuntu 24.04, 22.04, and 20.04. For Ubuntu, only even-numbered *.04
	releases are supported).
	* Rocky Linux 9, 8
	* Red Hat Enterprise Linux (RHEL) 9, 8
	* SuSE 15.

	This script recognizes SysV, Systemd.

	This script requires bash 4.x+ and works with bash 5.x.

	This script is not supported on Mac OSX. It recognizes the Launchd init
	mechanism on Mac but does not support it.

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

	* Yum: bc cronie curl file gawk lsof make nano neovim net-tools openssl openssl-devel policycoreutils-python-utils procps-ng rsync screen sos sysstat tar tmux tuned wget which zlib zlib-devel

	* AptGet: bc cron curl file gawk libbz2-dev libncurses5-dev libreadline-dev libsqlite3-dev libssl-dev llvm lsof make nano neovim net-tools policycoreutils-python-utils procps rsync screen sosreport sysstat tar tmux tuned wget zlib1g-dev

	* Zypper: bc cronie curl file gawk lsof make nano neovim net-tools openssl openssl-devel procps rsync screen sos sysstat tar tmux tuned wget which zlib zlib-devel

	If '-extra_pkgs' is used, the following packages are installed in
	addition to those listed 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. [email protected].  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 > sdp_install.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 P4 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 initialization of a P4 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 verified to not appear on
	on the OS root volume. If this is not the case, errors are given in
	pre-flight 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
	P4 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 available.

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

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

 -keep_env
	Specify this option if the OSUSER that operates services already exists
	and to preserve the original .bash_profile and .bashrc files.  This
	option is generally not advised because only the default .bash_profile
	and .bashrc files are guaranteed to work properly, e.g. sourcing the
	SDP environment and setting the standard prompt.  This option has no
    effect if the OSUSER ('perforce' by default) does not exist.

 -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 initial 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. P4 Binaries
	
	P4 binaries must exist in /opt/perforce/p4-sdp/p4_binaries:

	* /opt/perforce/p4-sdp/p4_binaries/p4
	* /opt/perforce/p4-sdp/p4_binaries/p4d
	* /opt/perforce/p4-sdp/p4_binaries/p4broker
	* /opt/perforce/p4-sdp/p4_binaries/p4p

	2. Server Deployment Package (SDP)

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

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

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

	curl -L -O https://workshop.perforce.com/download/p4-sdp/r25-1/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/p4-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 P4 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_replica.
	* p4broker - An SDP host running only a P4 Broker.
	* p4p - An SDP host running only a P4 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 simulator
	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).

 -sdp_overlay_dir <sdp_overlay_dir>
	Specify a directory containing files to be overlaid in the Writable
	Dir after files are copied from the Immutable dir. This can be used,
	for example, to add site-local files in /p4/common/site area during
	new installations, e.g. support Infrastructure as Code (IaC)
	deployments. The structure in the specified directory must be the
	same as the structure in the SDP tarball, though it may be
	sparsely populated. For example, to add SiteTags.sfg, specify
	'-t /iac/sdp' and have the '/iac/sdp' direcctory contain
	/iac/sdp/Server/Unix/p4/common/config/SiteTags.cfg.

    WARNING: This in intended to add files to the SDP structure, but can
    also be used to overwrite existing SDP files.  Doing so is not
    advised and is unsupported.

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.
 -V		Display version info.

 --help
	Alias for -man.

EXAMPLES:
	=== Demo Installation - P4 Server ===

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

	=== Typical Production P4 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:

	* /p4depots
	* /p4db
	* /p4logs

	These paths are typical, but are configurable. More information is available in
	the install configuration file generated 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://workshop.perforce.com/download/p4-sdp/r25.1/Server/Unix/setup/install_sdp.sh
	$ chmod +x install_sdp.sh

 	STEP 3: Generate install configuration 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 P4 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://workshop.perforce.com/download/p4-sdp/r25.1/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 P4 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/p4-sdp/p4_binaries
	$ cd /opt/perforce/p4-sdp/p4_binaries
	$ curl -L -O https://workshop.perforce.com/download/p4-sdp/r25.1/p4_binaries/get_p4_binaries.sh
	$ chmod +x get_p4_binaries.sh

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

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

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

	$ mkdir /opt/perforce/p4-sdp/downloads
	$ cd /opt/perforce/p4-sdp/downloads
	$ curl -O https://ftp.perforce.com/perforce/tools/sampledepot.tar.gz
	$ curl -L -O https://workshop.perforce.com/download/p4-sdp/r25-1/downloads/sdp.Unix.tgz

	Lastly, acquire this script:

	$ mkdir /root/install_sdp
	$ cd /root/install_sdp
	$ curl -L -O https://workshop.perforce.com/download/p4-sdp/r25.1/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.  To recap, for
	a '-local' install, the following files in this structure must exist on the
	machine on which the install is to occur:

	/root/install_sdp/install_sdp.sh
	/opt/perforce/p4-sdp/downloads/sdp.Unix.tgz
	/opt/perforce/p4-sdp/downloads/sampledepot.tar.gz (if the '-sampledepot' option is to be used).
	/opt/perforce/p4-sdp/p4_binaries/p4
	/opt/perforce/p4-sdp/p4_binaries/p4d
	/opt/perforce/p4-sdp/p4_binaries/p4broker
	/opt/perforce/p4-sdp/p4_binaries/p4p

	An install session would then look something like this:

	cd /root/install_sdp
	./install_sdp.sh -C > sdp_install.cfg         # Generate a config file
	vi sdp_install.cfg                            # Edit desired settings.
	./install_sdp.sh -c sdp_install.cfg -init     # Dry run. Review log to ensure success.
	./install_sdp.sh -c sdp_install.cfg -init -y  # Live run. Review log to ensure success.

	If the dry run is not successful, fix reported issues and try again.