USAGE for upgrade.sh v4.3.2:
upgrade.sh <instance> [-p] [-c] [-n] [-L <log>] [-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
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/<instance>/bin, (e.g. /p4/1/bin for instance
1), is expected to contain *_init scripts for services that operate on the
given machine.
For example, a typical master 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 phase execute depend on the what binaries
are 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.
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 constitue 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.
MASTER 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.
When the master server is upgraded, two rotations of the master server's journal
occur during processing. 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.
Later, after the p4d has started and p4d performs its journaled upgrade
processing, a second journal rotation occurs in Phase 5. This second journal
rotation captures all upgrade-related processing in a seprate numbered journal.
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.<short_hostname>.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 'uprade.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:
<instance>
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, procesing starts
immediately upon successful completion of prelfight checks.
-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 <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 this file
in the /p4/N/logs directory (where N is the SDP instance name):
upgrade.p4_N.<datestamp>.log
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.'
Logging can only be disabled with '-L off' if the '-n' or '-p' flags
are used. Disabling logging for actual upgrades is not allowed.
DEBUGGING OPTIONS:
-n No-Op. In No-Op mode, no actions that affect data or structures are
taken. Instead, commands that would be run are displayed. This
command can also be educational, showing various steps that will occur
during an upgrade.
-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: 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 executes the upgrade after successful completion of preflight checks,
and aborts if preflight checks detected any issues.
EXAMPLE 2: 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 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' paramter can be dropped, with simply a call to the script
needed:
$ upgrade.sh
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.