# Swarm Extension Upgrade Notes

In the same maintenance window where the P4 Code Review (fka Swarm) web app is upgraded, upgrade the extensions. This procedure describes how to upgrade the extensions.

Notes on Swarm Triggers vs. Swarm Extensions:

* This document describes how to upgrade Extensions if they are already in place.
* A happy Swarm installation includes the Swarm web app and either Swarm Extensions or Swarm Triggers.  Swarm provides both Extensions or Triggers, but any given installation will use only Swarm Triggers or Swarm Extensions, not both.  If your site is using Swarm Triggers, they should be upgraded instead.
* If you are using Triggers, you might opt to replace them with Extensions. Replacing Triggers with Extensions requires a review of your Triggers table and is outside the scope of this document. Replacing Triggers with Extensions is worthwhile to consider, as Extensions are expected to be better supported going forward.
* If Triggers are used, the upgrade procedure for Triggers depends on how Swarm Triggers were initially installed. That upgrade typically must occur on the P4D server machines in the fleet (commit server, standbys of the commit, edge servers, and standbys of the edge). It could be as simple as upgrading the `helix-swarm-triggers` OS package if the installation was done correctly, but could be more complex if triggers were installed differently. More details on upgrading triggers is also outside the scope of this document.

## Preflight Checks.

The Swarm web app itself should be upgraded using OS package upgrades.  If deploying a new Swarm installation or doing a migration-style upgrade (upgrading Swarm and the underlying OS by migrating to a new machine), the `/opt/perforce/swarm/sbin/configure_swarm.sh` should be run and verified before starting this procedure. The `configure_swarm.sh` script does not need to be run for in-place upgrades on an existing server machine.

## Upgrade Procedure

Swarm Extension upgrades are executed on the Swarm server machine, since that's where the `swarm-extctl.sh` script lives.  However, the actual processing occurs on the commit server machine, driven by the `swarm-extctl.sh` script on the Swarm server machine. Due to the nature of Extensions, they are replicated to other p4d servers in the fleet, so no per-server-machine upgrade is needed with Extensions as they are with Triggers. This procedure is complete even for p4d servers with large global topologies.

### STEP 1: Login as a super user

Operating as the operating system user `root` on your Swarm server machine, do:

Set P4USER to your SDP super user, not the Swarm web app or extension user. Set P4PORT to the P4PORT that reaches your commit server (or broker on the commit server if you're using brokers). For the hostname component, use the DNS name if it works, or an `/etc/hosts` entry, or an IP address if needed.

```
export P4USER=EDITME_YOUR_SDP_SUPER_USER
export P4PORT=EDITME_YOUR_P4PORT
```

It's OK to use non-persistent shell environment variables in a single terminal window for this operation, since we don't routinely need to operate as the super from the Swarm server machine.

Then login:

```
p4 -u $P4USER -p $P4PORT login
```

### STEP 2: Check Extensions

First, see what's in `/opt/perforce/etc` before we save the Swarm config.

```
ls -lrt /opt/perforce/etc/
```

Then upgrade the extensions.  When `swarm-extctl.sh` prompts for a password, just hit Enter and it should use the ticket generated by the login above.

```
cd /opt/perforce/swarm/sbin
```

Make sure current Extensions are good before we start.

```
./swarm-extctl.sh -u $P4USER -p $P4PORT ping 
```

The output should look something like this:
```
Checking to see if you are a super user... super
OK
Swarm Version: P4 Code Review/2026.3/3030911 (2026/08/06)
Extension Version: 2026.3/3030911
```

After the ping test, exercise the ability to trigger a review by creating and shelving a changelist with the `#review` tag in the description, ensuring the `#review` is replaced by `#review-<NNNNN>`.  Be patient; it may take several seconds after the review is shelved before the review ID appears. (Do not use P4V's 'Request Review' feature for this test; it exercises a different mechanism for creating reviews that doesn't exercise the Swarm extension).

If either the ping test or the review creation fails, this could indicate your current extensions are broken. Investigate and contact Perforce Technical Support ([email protected]) if needed.

### STEP 3: Save Old Extensions and Review

Continuing in the same terminal window, list the extensions. This is just a visual confirmation of what's already there.  The proceed with saving the current extensions:

```
./swarm-extctl.sh -u $P4USER -p $P4PORT list 
./swarm-extctl.sh -u $P4USER -p $P4PORT save
```

The output from the save should look like this:
```
Checking to see if you are a super user... super
Written to /opt/perforce/etc/swarm-extension.conf
Written to /opt/perforce/etc/swarm-extension.conf.inst
```

If desired, review those files backup `swarm-extension.conf*` files:

```
ls -lrt /opt/perforce/etc/
```

### STEP 4: Delete and Upgrade

Next, delete the old Swarm extensions and then immediately install the new ones, then run the ping again.

The 'delete' procedure here will delete only Swarm-related extensions.

```
./swarm-extctl.sh -y -u $P4USER -p $P4PORT delete 
./swarm-extctl.sh -y -u $P4USER -p $P4PORT install
./swarm-extctl.sh -u $P4USER -p $P4PORT install ping
```

That ping should have similar output as with the ping above, except that the version number should be different.

After the ping test, exercise the ability to trigger creating a review again, as was done above.

If either the ping test or the review creation fails with the newly installed extensions, this could indicate something went wrong with the extensions upgrade. Investigate and contact Perforce Technical Support ([email protected]) if needed.

### STEP 5: Logout super user

Finally, clear the ticket for the super user.

```
p4 -u $P4USER -p $P4PORT logout
```