Extensions Management

This section details how to manage the P4 Server Extensions. You can use the swarm-extctl.sh script file located in /opt/perforce/swarm/sbin directory to perform different actions on the P4 Server Extensions.

You must be logged in as a user with super user privileges to configure the P4 Server Extensions.

Upgrade the P4 Code Review extension

Upgrade the P4 Code Review extension whenever you upgrade P4 Code Review. Keeping the extension version aligned with the P4 Code Review version helps prevent compatibility issues and simplifies troubleshooting.

Upgrade the extension during the same maintenance window as the P4 Code Review upgrade.

P4 Code Review installations typically use either P4 Server Extensions or P4 Server Triggers. Most installations use one approach or the other, but not both. If your deployment uses the P4 Code Review extension, follow the procedure below after upgrading P4 Code Review. If your deployment uses triggers instead of extensions, follow your site's trigger upgrade procedure (see Installing triggers).

Upgrading P4 Code Review does not automatically upgrade an existing P4 Code Review extension.

After upgrading P4 Code Review, upgrade the extension to ensure that both components are running compatible versions.

Before you begin

Upgrade the P4 Code Review application before upgrading the extension.
For migration-based upgrades or new installations, complete the P4 Code Review installation and configuration process before upgrading the extension.
Ensure that you are logged in as a user with super privileges.
Ensure that the swarm-extctl.sh script is available in the /opt/perforce/swarm/sbin directory.

Extension upgrades are initiated from the P4 Code Review server using the swarm-extctl.sh script. The extension is then replicated by P4 Server, so you do not need to upgrade the extension separately on each server in your topology.

Upgrade the extension

Navigate to the directory that contains the swarm-extctl.sh script:
```
cd /opt/perforce/swarm/sbin
```
To verify the currently installed extension version, run:
```
 ./swarm-extctl.sh ping
```
Confirm that the command completes successfully and note the current extension version.

Save the current extension configuration:

 ./swarm-extctl.sh  save

The configuration is saved to:

/opt/perforce/etc/swarm-extension.conf
/opt/perforce/etc/swarm-extension.conf.inst

Delete the existing extension installation:
```
 ./swarm-extctl.sh delete
```
Install the updated extension:
```
 ./swarm-extctl.sh  install
```
Any previously saved extension configuration is automatically applied during installation.
To verify that the extension upgraded successfully, run

./swarm-extctl.sh ping

Confirm that the reported extension version matches the installed P4 Code Review version.

Verify extension functionality

After the upgrade, verify that the extension is functioning correctly by creating a test review and confirming that review creation and processing work as expected.

If review creation or processing fails, review the extension configuration and version information before contacting Perforce Technical Support.

Extension commands

You can use the following commands to manage the P4 Server Extensions:

List
Delete
Install
Config
Tokens
Disable
Enable
Save
Load
Ping

List

Description

Lists all the installed Extensions and their configurations.

Commands run

Runs the list command.

swarm-extctl list

The swarm-extctl.sh script responds with:

... config swarm
... extension Perforce::helix-swarm
... uuid 4532BC59-7BC8-478F-ADF6-0A563C42563D
... revision 1
... owner super
... type change-commit
... arg //...
... debugStatus none

... config swarm
... extension Perforce::helix-swarm
... uuid 4532BC59-7BC8-478F-ADF6-0A563C42563D
... revision 1
... owner super
... type change-content
... arg //...
... debugStatus none

... config swarm
... extension Perforce::helix-swarm
... uuid 4532BC59-7BC8-478F-ADF6-0A563C42563D
... revision 1
... owner super
... type change-submit
... arg //...
... debugStatus none

Delete

Description

Deletes the P4 Server extension and their configurations.

Commands run

Runs the delete command.

swarm-extctl delete

The swarm-extctl.sh script responds with:

Checking to see if you are a super user... super
Deleting the configuration
Are you really sure (y/n)?
y
Extension 'Perforce::helix-swarm and its configurations' successfully deleted.

Install

Description

Installs the P4 Server extension. The helix-swarm.p4-extension file located in swarm_root/p4-bin/extensions directory is used to install Extensions.

For more information about installing P4 Server extension, see Installing the P4 Code Review extension for P4 Server (recommended).

After installation, the saved configurations are automatically applied to the extension. For more information about the saved configurations, see Save command.

Commands run

Runs the install command.

swarm-extctl install

The swarm-extctl.sh script responds with:

Checking to see if you are a super user... super
Installing the configuration
Are you really sure (y/n)?
y
Extension 'Perforce::helix-swarm' version '2023.1/2414875' installed successfully.
Perform the following steps to turn on the Extension:

# Create a global configuration if one doesn't already exist.
p4 extension --configure Perforce::helix-swarm

# Create an instance configuration to enable the Extension.
p4 extension --configure Perforce::helix-swarm --name swarm

For more information, visit:
https://www.perforce.com/manuals/v23.1/extensions/Content/Extensions/Home-extensions.html

Reading configuration from /opt/perforce/etc/swarm-extension.conf

Extension config helix-swarm saved.

Reading configuration from /opt/perforce/etc/swarm-extension.conf.inst

Extension config swarm saved.

Config

Description

Lists the global configuration and instance configuration for the installed Extensions.

The global configuration is retrieved from /opt/perforce/etc/swarm-extension.conf file and the instance configuration is retrieved from /opt/perforce/etc/swarm-extension.conf.inst file. If no configuration files are available, the extension specification file opens in your text editor. You can edit the specification file and save it in your text editor.

Commands run

Runs the config command.

swarm-extctl config

The swarm-extctl.sh script responds with:

The global configuration and instance configuration opened in your text editor.
Here is a sample global configuration specification for P4 Server extension:

# A Perforce Extension Specification.
#
#  ExtName:          The name of the Extension being configured.
#  ExtDescription:   The description of the Extension being configured.
#  ExtVersion:       The version of the Extension being configured.
#  ExtUUID:          The UUID/key of the Extension being configured.
#  ExtRev:           The revision of the Extension being configured.
#  ExtMaxScriptTime: Maximum seconds the Extension may be run.
#  ExtMaxScriptMem:  Maximum megabytes the Extension may use.
#  ExtAllowedGroups: Groups whose members may configure the Extension.
#  ExtEnabled:       Enable/Disable this Extension.
#  ExtP4USER:        Perforce user account for the Extension to use.
#  Name:             The name of this Extension config.
#  Owner:            The user who created this Extension config.
#  Update:           Update time for the Extension config spec.
#  Description:      The description of this Extension config.
#  ExtConfig:        Extension-supplied configuration fields.
#
# See 'p4 help extension' for detailed information.

ExtName:        helix-swarm

ExtDescription:
        Helix Swarm Extension

ExtVersion:     2023.1/2414875

ExtUUID:        4532BC59-7BC8-478F-ADF6-0A563C42563D

ExtRev: 1

ExtMaxScriptTime:       unset

ExtMaxScriptMem:        unset

ExtAllowedGroups:

ExtEnabled:     true

ExtP4USER:      super

Name:   helix-swarm

Owner:  super

Update: 2023/03/07 15:35:18

Description:
           This is the Helix Swarm extension, which replaces the old Perl
           trigger that was used previously. If this is installed and
           configured, then the Swarm triggers MUST be removed.
           This file configures the connection to the Swarm server. Only one 
           Swarm instance can manage a single Helix server.

ExtConfig:
        Swarm-URL:      http://localhost/
       
        Swarm-Token:    785D3DD6-304D-5FCA-AF47-751578849960

        Swarm-Secure:   true

        Debug:  3

After you edit the specification file and save it in your text editor.

Extension config helix-swarm saved.
Extension config swarm saved.

Tokens

Description

Lists the trigger tokens available for a P4 Server including the multiple P4 Server (P4D) instances. The tokens are saved in /opt/perforce/swarm/data/queue/tokens directory. The Swarm installation folder is /opt/perforce/swarm/.

Commands run

Runs the tokens command.

swarm-extctl tokens

The swarm-extctl.sh script responds with:

Checking to see if you are a super user... super
Available tokens:
785D3DD6-304D-5FCA-AF47-751578849960

Disable

Description

Disables the P4 Server extension configuration.

Commands run

Runs the disable command.

swarm-extctl disable

The swarm-extctl.sh script responds with:

Checking to see if you are a super user... super
Disabled

Enable

Description

Enables the P4 Server extension configuration.

Commands run

Runs the enable command.

swarm-extctl enable

The swarm-extctl.sh script responds with:

Checking to see if you are a super user... super
Enabled

Save

Description

Saves the global configuration to /opt/perforce/etc/swarm-extension.conf file and the instance configuration to /opt/perforce/etc/swarm-extension.conf.inst file.

Commands run

Runs the save command.

swarm-extctl save

The swarm-extctl.sh script responds with:

Checking to see if you are a super user... super
Extension config helix-swarm saved.
Extension config swarm saved.

Load

Description

Loads the global configuration from /opt/perforce/etc/swarm-extension.conf file and the instance configuration from /opt/perforce/etc/swarm-extension.conf.inst file.

Commands run

Runs the P4 Code Review load command.

swarm-extctl load

The swarm-extctl.sh script responds with:

Checking to see if you are a super user... super
Extension config helix-swarm saved.
Extension config swarm saved.

Ping

Description

Lists the version and status of the P4 Server extension.

Commands run

Runs the ping command.

swarm-extctl ping

The swarm-extctl.sh script responds with:

Checking to see if you are a super user... super
OK
Swarm Version: SWARM/2023.1/2414875 (2023/03/07)
Extension Version: 2023.1/2414875