p4 extension

Create and configure P4 Extensions.

Syntax

p4 extension --sample extName
p4 extension --package dir [--sign keyDir]
p4 extension --install extName.p4-extension [--yes]
p4 extension --install certificateFile --cert [ --comment ]
p4 extension --delete extFQN [ --name instName ] [ --revision=n ]
             [ --path FileSpec ] [--yes]
p4 extension --delete fingerprint --cert
p4 extension --configure extFQN [ --revision=n ] [ -o | -i ]
p4 extension --configure extFQN [ --revision=n ] [ -o | -i ]
             --name instName
p4 extension --run  instName [ extArguments ]
p4 extension --list --type type [--path FileSpec]

Syntax conventions

Description

Extensions are a means for customizing parts of the P4 with user-supplied logic. Extensions are self-contained packages of third-party code and assets that run within the P4 Server. Typical use cases are change submission validation, form validation, external authentication, external job fix integration, external archive integration, and command policies.

An Extension can implement custom commands that a user can run. For example,

p4 extension --run myInstanceConfig validateFileSize pathToFile

where validateFileSize represents a custom command and pathToFile represents an argument that is relevant to the custom command.

Extensions coexist with p4 triggers, but offer more functionality. To learn more, see Advantages over triggers in the Extension overview at P4 Server Administration Documentation.

The P4 Server runs extensions natively, without relying on external processes. Extensions run in a portable, versioned runtime with automatic replication and a programmatic API, which is documented at P4 Server Administration Documentation.

The p4 extension command requires super access granted by p4 protect. Users who are members of groups specified in the ExtAllowedGroups field of an extension's global configuration and who are either a depot or repo owner can create or configure instances of file-based extensions to operate on the sections of the server they manage.

Extensions are versioned within the P4 Server and are stored in the built-in .p4-extensions depot. The extension depot is only accessible to the super user and by read-only commands.

Installing or upgrading an extension creates a changelist with information about pre/post install versions. Multiple revisions of an extension can be active at any given time and can be referenced by their revision number.

Extension configuration

An extensions consists of a global configuration and an instance configuration.

The global configuration applies to all instances of a particular server extension. For example, to enable all instances of a server extension to send an email, the name of the mail server would be configured globally by a super user using a command similar to this:

p4 extension --configure ExampleInc::extName.

One or more instance configurations will use the globally defined parameters but also have parameters that are unique to the instance. For example, Release1.0-fileSizeCheck-instance1 might apply to //depot/test and specify a maximum file size and a maximum number of files, while Release1.0-fileSizeCheck-instance2 might apply to //depot/main and specify a different maximum file size and a different maximum number of files.

For example, an instance configuration can be assigned with a command similar to this:

p4 extension --configure ExampleInc::extName --name Release1.0-fileSizeCheck

Naming rules

Extensions are referred to by their fully-qualified name. This is the combination of the namespace, name, and, optionally, the revision of the extension that is installed on a server, as opposed to the version of the extension code. For example, a namespace of ExampleInc and a name of ExtName are referred to as ExampleInc::ExtName

Options

--sample

Create a skeleton of a new Extension in a directory. Pass it the name of the Extension to be created. (See Naming rules.)

p4 extension --sample ExtName

This allows you to then use the --package option.

--package

The --package option creates a packaged Extension file from the named directory of files. For example,

p4 extension --package ExtName

The resulting file has the same name as the directory, but with the .p4-extension suffix. An Extension must be packaged before it can be installed by using the --install option.
--yes

To actually perform the install or delete, the --yes option is required. Without --yes, the p4 extension command merely reports what it would do without actually performing the install or delete.

-y is equivalent to --yes
--install

The full name of an Extension file on the client. The command installs it server-side. Packaged Extensions have the p4-extension file suffix.

For example,

p4 extension --install ExtName.p4-extension --yes

To actually perform the install or delete, the --yes option is required. Without --yes, the p4 extension command merely reports what it would do without actually performing the install or delete.
--name

The name of the instance configuration to create, modify, or delete.
--revision

Which depot version of the Extension to configure. The default is the head revision. This option applies to the --configure option.

This flag applies to the --configure option when used with or without the --name option.
--configure

An Extension is not active until it has been configured. In this syntax:

p4 extension --configure extFQN [ --revision=n ] [ -o | -i ]

extFQN means fully-qualified name: the combination of the Extension's namespace, name, and optional depot file revision.

The default global configuration is:

p4 extension --configure ExampleInc::myExt

and your global configuration might be:

p4 extension --configure myCompany::fileSizeCheck

and the corresponding instance configuration might be:

p4 extension --configure myCompany::extName --name Release1.0-fileSizeCheckInst

An Extension can have multiple configurations, depending on the events it registers for. Each configuration of an Extension can point to a different version of the Extension.
--list

Displays the installed extensions and their instances.

To list all Extensions:

p4 extension --list --type extensions

To list all instance configurations:

p4 extension --list --type configs

You can replace --type configs with --type global or --type instance to filter results accordingly.

Adding --path path filters output to instance configurations that are path-based and their path argument matches the given path.

The output of p4 extension --list --type extensions indicates the status of extension configuration:

  • status Requires a global configuration

  • status Requires instance configuration to enable the extension

  • status Global and instance configuration enabled

For an extension to be active, an extension must have a global configuration and at least one instance configuration.
--delete

Deletes an extension, its configurations, or both.

  • To remove the named instance config, include the --name option:
    p4 extension --delete myCompany::fileSizeCheck
    --name fileSizeCheck-instance --yes
  • To remove all revisions of an extension and its configurations, omit the
    --name     option:
    p4 extension --delete myCompany::fileSizeCheck
  • To remove one specific revision and its instances, include the
    --revision     option:
    p4 extension --delete myCompany::fileSizeCheck
    --revision=2 --yes
  • To delete file-based instances registered under the specified path:

    p4 extension --delete ExampleInc::extD1
    --path //depot/... --yes

To perform the install or delete, the --yes option is required. Without --yes, the p4 extension command merely reports what it would do without actually performing the install or delete.

extFQN means fully-qualified name: the combination of the Extension's namespace, name, and optional depot file revision.
--allow-unsigned (Optional) If included in the commands to install (or delete) an extension, it is the same as if the server.extensions.allow.unsigned configurable were set to 1 so that the extension does not need to be signed.

-i

Read the extension definition from standard input.

-o

Write the extension definition from to standard output.
--run

Executes the specified Extension.

An Extension can implement custom end-user commands, executed by passing the --run flag the name of an instance config and supplying any optional arguments the Extension might need.

--sign Can be supplied in --package
--cert

Can be supplied in --install or --delete

For example,
p4 extension --install path/certificate.txt --cert --comment "We trust ACTools"
--comment Can be supplied in --install or --delete

For example,
p4 extension --install path/certificate.txt --cert --comment "We trust ACTools"
--type Must be supplied with --list

Possible type values: extensions, global, instance, certs, configs (both global and instance).

For example,

p4 extension --list --type certs

Usage notes

Can File Arguments Use Revision Specifier? Can File Arguments Use Revision Range? Minimal Access Level Required

N/A

N/A

Instance configuration permissions for users

The super user's delegation of instance configuration behaves differently for admin users and normal users.

normal admin super

The super user can grant permission to a normal user to deploy and configure the instance settings with 

p4 extension --configure ExampleInc::checkcase --name ExampleInc::checkcase

if all the following are true:

  • The user is a member of a group configured in ExtAllowedGroups in the global configuration.

  • The protections table has an entry for that group with an access level of owner

  • The protections table entry has the path defined matching that specified in the InstanceConfigEvents() callback in the extension code.

An admin user cannot install, configure, or delete a server-side extension unless that extension is signed and the server.extensions.allow.admin configurable is set to 1

The super user can override server.extensions.allow.unsigned being set to 0, by adding

--allow-unsigned

to the --install or --delete options.