USAGE for upgrade.sh v4.12.2: upgrade.sh [-p|-I] [-M] [-Od] [-Osp] [-c] [-y] [-L ] [-d|-D] or upgrade.sh [-h|-man] DESCRIPTION: This script upgrades the following Helix Core software: * p4d, the Perforce Helix Core server * p4broker, the Helix Broker server * p4p, the Helix Proxy server * p4, the command line client The preferred process for using this script is to start with the services to be upgraded (p4d, p4broker, and/or p4p ) up and running at the start of processing. The p4d service must be online if it is to be upgraded. Details of each upgrade are described below. Prior to executing any upgrades, a preflight check is done to help ensure upgrades will go smoothly. Also, checks are done to determine what (if any) of the above software products need to be updated. To prepare for an upgrade, new binaries must be update in the /p4/sdp/helix_binaries directory. This is generally done using the get_helix_binaries.sh script in that directory. Binaries in this directory are not referenced by live running servers, and so it is safe to upgrade files in this directory to stage for a future upgrade at any time. Also, the SDP standard PATH does not include this directory, as verified by the verify_sdp.sh script. THE INSTANCE BIN DIR The 'instance bin' directory, /p4//bin, (e.g. /p4/1/bin for instance 1), is expected to contain *_init scripts for services that operate on the current machine. For example, a typical commit server machine for instance 1 might have the following in /p4/1/bin: * p4broker_1_init script * p4broker_1 symlink * p4d_1_init script * p4d_1 symlink or script * p4_1 symlink (a reference to the 'p4' command line client) A server machine for instance 1 that runs only the proxy server would have the following in /p4/1/bin: * p4p_1_init script * p4p_1 symlink * p4_1 symlink The instance bin directory is never modified by the 'upgrade.sh' script. The addition of new binaries and update of symlinks occur in . The existence of *_init scripts for any given binary determines whether this script attempts to manage the service on a given machine, stopping it before upgrades, restarting it afterward, and other processing in the case of p4d. Note that Phase 2, adding new binaries and updating symlinks, will occur for all binaries for which new staged versions are available, regardless of whether they are operational on the given machine. THE COMMON DIR This script performs it operations in the SDP common bin dir, . Unlike the instance bin directory, the directory is expected to be identical across all machines in a topology. Scripts and symlinks should always be the same, with only temporary differences while global topology upgrades are in progress. Thus, all binaries available to be upgraded will be upgraded in Phase 2, even if the binary does not operate on the current machine. For example, if a new version of 'p4p' binary is available, a new version will be copied to and symlink references updated there. However, the p4p binary will not be stopped/started. GENERAL UPGRADE PROCESS This script determines what binaries need to be upgraded, based on what new binaries are available in the /p4/sdp/helix_binaries directory compared to what binaries the current instance uses. There are 5 potential phases. Which phases execute depend on the set of binaries being upgraded. The phases are: * PHASE 1 - Establish a clean rollback point. This phase executes on the master if p4d is upgraded. * PHASE 2 - Install new binaries and update SDP symlinks in . This phase executes for all upgrades. * PHASE 3 - Stop services to be upgraded. This phase executes for all upgrades involving p4d, p4p, p4broker. Only a 'p4' client only upgrade skips this phase. * PHASE 4 - Perforce p4d schema upgrades This step involves the 'p4d -xu' processing. It executes if p4d is upgraded to a new major version, and occurs on the master as well as all replicas/edge servers. The behavior of 'p4d -xu' differs depending on whether the server is the master or a replica. This phase is skipped if upgrading to a patch of the same major version, as patches do not require 'p4d -xu' processing. * PHASE 5 - Start upgraded services. This phase executes for all upgrades involving p4d, p4p, p4broker. Only a 'p4' client only upgrade skips this phase. SPECIAL CASE - TO OR THRU P4D 2019.1 If you are upgrading from a version that is older than 2019.1, services are NOT restarted after the upgrade in Phase 5, except on the master. Services must be restarted manually on all other servers. For these 'to-or-thru' 2019.1 upgrades, after ensuring all replicas/edges are caught up (per 'p4 pull -lj'), shutdown all servers other than the master. Proceeding outer-to-inner, execute this script like so on all machines except the master: 1. Deploy new executables in /p4/sdp/helix_binaries 2. Stop p4d. 3. Run 'verify_sdp.sh -skip cron,version'; fix problems if needed until it reports clean. 4. Run 'upgrade.sh -M' to update symlinks. 5. Do the upgrade manually with: p4d -xu 6. Leave the server offline. On the master, execute like this: 1. Deploy new executables in /p4/sdp/helix_binaries 2. Run 'verify_sdp.sh -skip cron,version'; fix problems if needed until it reports clean. 3. upgrade.sh When the script completes (it will wait for 'p4 storage' upgrades), restart services manually after the upgrade in the 'inner-to-outer' direction. Restart services on replicas/edges going inner-to-outer This procedure requiring extra steps is specific to 'to-or-thru' P4D 2019.1 upgrades. For upgrades starting from P4D 2019.1 or later, things are simpler. UPGRADES FOR P4D 2019.1+ For upgrades where the P4D start version is 2019.1 and going to any subsequent version, run this script going outer-to-inner. On each machine, it leaves the services online and running. Going in the outer-to-inner direction an all servers, do: 1. Deploy new executables in /p4/sdp/helix_binaries 2. Run 'verify_sdp.sh -skip cron,version'; fix problems if needed until it reports clean. 3. upgrade.sh UPGRADE PREPARATION The steps for deploying new binaries to server machines and running verify_sdp.sh (and potentially correcting any issues it discovers) can and should be done before the time or even day of any planned upgrade. UPGRADING HELIX CORE - P4D The p4d process, the Perforce Helix Core Server, is the center of the Perforce Helix universe, and the only server with a significant database component. Most of the upgrade phases above are about performing the p4d upgrade. This 'upgrade.sh' script requires that the 'p4d' service be running at the beginning of processing if p4d is to be upgraded, and will abort if p4d is not running. ORDER OF UPGRADES Any given Perforce Helix installation will have least one p4d master server, and may have several other p4d servers deployed on different machines as replicas and edge servers. When upgrading multiple p4d servers for any given instance (i.e. any given data set, with a unique set of changelist numbers and users), the order in which upgrades are performed matters. Upgrades must be done in "outer to inner" order. The master server, at the center of the topology, is the innermost server and must be upgraded last. Any replicas or edge servers connected directly to the master constitute the next outer circle. These can be upgraded in any order relative to each other, but must be done before the master and after any replicas farther out from the master in the topology. So this 'upgrade.sh' script should be run first on the server machines that are "outermost" from the master from a replication perspective, and moving inward. The last run is done on the master server machine. Server machines running only proxies and brokers do not have a strict order dependency for upgrades. These are commonly done in the same "outer to inner" methodology as p4d for process consistency rather than strict technical need. See the SDP_Guide.Unix.html for more information related to performing global topology upgrades. COMMIT SERVER JOURNAL ROTATIONS This script helps minimize downtime for upgrades by taking advantage of the SDP offline checkpoint mechanism. Rather than wait for a full checkpoint, a journal is rotated and replayed to the offline_db. This typically takes very little time compared to a checkpoint, reducing downtime needed for the overall upgrade. It also prepares the offline_db in case a rollback is needed. When the commit server is upgraded, two rotations of the commit server's journal occur during processing for major upgrades, and a single journal rotation is done for patch upgrades. The first journal rotation occurs before any upgrade processing occurs, i.e. before the new binaries are added and symlinks are updated. This gives a clean rollback point. This journal is immediately replayed to the offline_db. Later, after p4d has started performs its journaled upgrade processing, a second journal rotation occurs in Phase 5 if a major upgrade was done. This second journal rotation captures all upgrade-related processing in a separately numbered journal. This second journal is not applied to the offline_db by this script. Instead, the replay of the second journal to the offline_db will occur the next time a call is made to the daily_checkpoint.sh or rotate_journal.sh, e.g. via routine crontab. For a p4d patch upgrade, there will not be any upgrade processing. In the very unlikely event that a rollback were to ever be needed, the offline_db is left in a state that it could be used for a fast rollback on the commit server. MULTI-SERVER OUTER-TO-INNER UPGRADES Before starting an outer-to-inner upgrade involving multiple p4d servers, (standby, edge, and other p4d replica servers), a manual journal rotation should be done on the commit server before starting to call upgrade.sh on each of the p4d servers in outer-to-inner order. Take note of the journal counter used for this pre-start journal rotation. It can be useful in event of a rollback. That journal may need to be replayed to the offline_db on all servers other than the commit in a rollback scenario. In prepartion in days or weeks before an upgrade, every p4d server in the topology should be checked to ensure its offline_db is healthy and current. ROLLBACK In the very unlikely event that a rollback is needed, bear in mind the following: * There is no standard procedure for rolling back, because a procedure would need to take into account the reason a decision was made to rollback. Presumably the decision would be driven by some kind of failure. A large factor in determining whether rollback is practical is the point in the process at which a rollback is needed. In some situations, a 'Fix and Roll Forward' approach may be more pragmatic than a rollback, and should always be considered. * This script and supporting documentation will help prepare your data for as smooth a rollback as possible should it ever become necessary. * To best prepare for a rollback, it is essential to manage user lockout as part of your overall maintenance procedure. Then let users back in after you have confirmed you are moving forward. User lockout is outside the scope of this script, but can be managed using several possible methods such as: - Crafting a special Protections table to be used during maintenance, - Using "Down for Maintenance" brokers, - Using network and/or on-host firewall rules, - Using temporary ports for maintenance. * If Phase 2 (update of symlinks and binaries) completed and must be undone, than can be achieved by putting the pre-upgrade binaries in place in the directory /p4/sdp/helix_binaries, named simply p4, p4d, p4broker, and p4p. Then run a command like this example for Instance 1: upgrade.sh 1 -M -I -y This will change symlinks back to reference the older versions. The new binaries will still exist in /p4/common/bin, but will no longer be referenced for Instance 1. UPGRADING HELIX BROKER Helix Broker (p4broker) servers are commonly deployed on the same machine as a Helix Core server, and can also be deployed on stand-alone machines (e.g. deployed to a DMZ host to provide secure access outside a corporate firewall). Helix Brokers configured in the SDP environment can use a default configuration file, and may have other configurations. The default configuration is the done defined in /p4/common/config/p4_N.broker.cfg (or a host-specific override file if it exists named /p4/common/config/p4_N.broker..cfg). Other broker configurations may exist, such as a DFM (Down for Maintenance) broker config /p4/common/config/p4_N.broker.dfm.cfg. During upgrade processing, this 'upgrade.sh' script only stops and restarts the broker with the default configuration. Thus, if coordinating DFM brokers, first manually shutdown the default broker and start the DFM brokers before calling this script. This script will leave the DFM brokers running while adding the new binaries and updating the symlinks. (Note: Depending on how services are configured, this DFM configuration might not survive a machine reboot. typically the default broker will come online after a machine reboot). This 'upgrade.sh' script will stop the p4broker service if it is running at the beginning of processing. If it was stopped, it will be restarted after the new binaries are in place and symlinks are updated. If p4broker was not running at the start of processing, new binaries are added and symlinks updated, but the p4broker server will not be started. UPGRADING HELIX PROXY Helix Proxy (p4p) are commonly deployed on a machine by themselves, with no p4d and no broker. It may also be run on the same machine as p4d. This 'upgrade.sh' script will stop the p4p service if it is running at the beginning of processing. If it was stopped, it will be restarted after the new binaries are in place and symlinks are updated. If p4p was not running at the start of processing, new binaries are added and symlinks updated, but the p4p server will not be started. UPGRADING HELIX P4 COMMAND LINE CLIENT The command line client, 'p4', is upgraded in Phase 2 by addition of new binaries and updating of symlinks. STAGING HELIX BINARIES If your server can reach the Perforce FTP server over the public internet, a script can be used from the /p4/sdp/helix_binaries directory to get the latest binaries: $ cd /p4/sdp/helix_binaries $ ./get_helix_binaries.sh If your server cannot reach the Perforce FTP server, perhaps due to outbound network firewall restrictions or operating on an "air gapped" network, use the '-n' option to see where Helix binaries can be acquired from: $ cd /p4/sdp/helix_binaries $ ./get_helix_binaries.sh -n OPTIONS: Specify the SDP instance name to add. This is a reference to the Perforce Helix Core data set. This defaults to the current instance based on the $SDP_INSTANCE shell environment variable. If the SDP shell environment is not loaded, this option is required. -p Specify '-p' to halt processing after preflight checks are complete, and before actual processing starts. By default, processing starts immediately upon successful completion of preflight checks. -Od Specify '-Od' to override the rule preventing downgrades. WARNING: This is an advanced option intended for use by or with the guidance of Perforce Support or Perforce Consulting. -Osp Specify '-Osp' to override the sudo preflight, skipping that check. WARNING: This is an advanced option intended for use by or with the guidance of Perforce Support or Perforce Consulting. -I Specify '-I' to ignore preflight errors. Use of this flag is STRONGLY DISCOURAGED, as the preflight checks are essential to ensure a safe and smooth migration. If used, preflight checks are still done so their errors are recorded in the upgrade log, and then the migration will attempt to proceed. WARNING: This is an advanced option intended for use by or with the guidance of Perforce Support or Perforce Consulting. -M Specify '-M' if you plan to do a manual upgrade. With this option, only Phase 2 processing, adding new staged binaries and updating symlinks, is done by this script. If '-M' is used, this script does not check that services to be upgraded are online at the start of processing, nor does it attempt to start to stop services. If '-M' is used, the services should be stopped manually before calling this script, and then started manually after. WARNING: This is an advanced option intended for use by or with the guidance of Perforce Support or Perforce Consulting. -c Specify '-c' to execute a command to upgrade the Protections table comment format after the p4d upgrade, by using a command like: p4 protect --convert-p4admin-comments -o | p4 -s protect -i By default, this Protections table conversion is not performed. In some environments with custom policies related to update of the protections table, this command may not work. The new style of comments and the '--convert-p4admin-comments' option was introduced in P4D 2016.1. -L Specify the path to a log file, or the special value 'off' to disable logging. By default, all output (stdout and stderr) goes to this file in the /p4/N/logs directory (where N is the SDP instance name): upgrade.p4_N..log NOTE: This script is self-logging. That is, output displayed on the screen is simultaneously captured in the log file. Redirection operators like '> log' and '2>&1' are not required, nor is 'tee'. Logging can only be disabled with '-L off' if the '-n' or '-p' flags are used. Disabling logging for actual upgrades is not allowed. -y Specify the '-y' option to confirm that the upgrade should be done. By default, this script operates in No-Op mode, meaning no actions that affect data or structures are taken. Instead, commands that would be run are displayed. This mode can be educational, showing various steps that will occur during an actual upgrade. DEBUGGING OPTIONS: -d Increase verbosity for debugging. -D Set extreme debugging verbosity, using bash '-x' mode. Also implies -d. HELP OPTIONS: -h Display short help message -man Display man-style help message EXAMPLES: EXAMPLE 1: Preflight Only To see if an upgrade is needed for this instance, based on binaries staged in /p4/sdp/helix_binaries, use the '-p' flag to execute only the preflight checks, and disable logging, as in this example: $ cd /p4/common/bin $ ./upgrade.sh 1 -p -L off EXAMPLE 2: Typical Usage Typical usage is with just the SDP instance name as an argument, e.g. instance '1', and no other parameters, as in this example: $ cd /p4/common/bin $ ./upgrade.sh 1 This first runs preflight checks, and aborts if preflight checks detected any issues. The it gives a preview of the upgrade. A successful preview completes with a line near the end that looks like this sample: Success: Finished p4_1 Upgrade. If the preview is successful, then proceed with the real upgrade using the -y flag: $ ./upgrade.sh 1 -y EXAMPLE 3: Simplified If the standard SDP shell environment is loaded, upgrade.sh will be in the path, so the 'cd' command to /p4/common/bin is not needed. Also, the SDP_INSTANCE shell environment variable will be defined, so the 'instance' parameter can be dropped, with simply a call to the script needed. First do a preview: $ upgrade.sh Review the output of the preview, looking for the 'Success: Finished' message near the end of the output. If that exists, then execute again with the '-y' flag to execute the actual migration: $ upgrade.sh -y CUSTOM PRE- AND POST- UPGRADE AUTOMATION HOOKS: This script can execute custom pre- and post- upgrade scripts. This can be useful to incorporate site-specifc elements of an upgrade. If the file /p4/common/site/upgrade/pre-upgrade.sh exists and is executable, it will be executed as a pre-upgrade script. If the file /p4/common/site/upgrade/post-upgrade.sh exists and is executable, it will be executed as a post-upgrade script. Pre- and post- upgrade scripts are called with an SDP instance parameter, and an optional '-y' flag to confirm actual processing is to be done. Custom scripts are expected to operate in preview mode by default, taking no actions that affect data (just as this script behaves). If this upgrade.sh script is given the '-y' flag, that option is passed to the custom script as well, indicating active processing should occur. Pre- and post- upgrade scripts are expected to exit with a zero exit code to indicate success, and non-zero to indicate failure. The custom pre-upgrade script is executed after standard preflight checks complete successfully. If the '-I' flag is used to ignore the status of preflight checks, the custom pre-upgrade script is executed regardless of the status of preflight checks. Preflight checks are executed before actual upgrade processing commences. If a custom pre-upgrade script indicates a failure, the overall upgrade process aborts. The post-upgrade custom script is executed after the main upgrade is successful. Success or failure of pre- and post- upgrade scripts is reported in the log. These scripts do not require independent logging, as all standard and error output is captured in the log of this upgrade.sh script. TIP: Be sure to fully test custom scripts in a test environment before incorporating them into an upgrade on production systems. SEE ALSO: The /verify_sdp.sh script is used for preflight checks. The /p4/sdp/helix_binaries/get_helix_binaries.sh script acquires new binaries for upgrades. Both scripts sport the same '-h' (short help) and '-man' (full manual) usage options as this script. LIMITATIONS: This script does not handle upgrades of 'p4dtg', Helix Swarm, Helix4Git, or any other software. It only handles upgrades of p4d, p4p, p4broker, and the p4 client binary on the SDP-managed server machine on which it is executed.