Table of Contents

Loading ...

Stack Plugins

A wazo-platform deployment can be extended with plugins, managed by the wazo-plugind component.

Plugins allow third parties to add functionality to Wazo, such as custom dialplan, configuration files, and service extensions.

Managing Plugins with wazo-plugind-cli

The wazo-plugind-cli command-line tool can be used to manage plugins. It interacts with the wazo-plugind REST API.

Listing Plugins

List all installed plugins:

wazo-plugind-cli -c "list"

Installing Plugins

wazo-plugind-cli -c "install <method> <source> [--ref reference] [--async]"

For example, to install a plugin official/myplugin from a github source, with a tag reference for a specific version:

wazo-plugind-cli -c "install git https://github.com/myorg/myplugin --ref v1.0"
Private plugins

A plugin hosted in a private git repository may be installed if a credential can be embedded in the URL. For example, a github private plugin can be installed using an access token with the correct permissions:

wazo-plugind-cli -c "install git https://<access token>@github.com/myorg/myprivateplugin"

This depends on the git hosting service's support for private repository access URLs.

Git versioning

A git plugin may be installed from a specific branch, or a specific reference, using the --ref option. With no --ref, the default branch name master is used.

A branch is a mutable reference, so installing from a branch may install an arbitrary version of the plugin source at different moments in time, which may result in installing an unstable version. Consult the plugin documentation, release notes or commit history of the source repository to determine if a branch reference is appropriate or a specific tag or commit revision is available.

In general, a fixed reference, such as a tag or a specific commit revision, is preferable to guarantee a specific version is installed, and that the installation command can safely be reused with the same expected result.

Uninstalling Plugins

Uninstall an installed plugin through its full name:

wazo-plugind-cli -c "uninstall <namespace>/<name>"

See Listing plugins to see installed plugins and their full name.

Reinstalling Plugins

To reinstall a plugin (e.g. after a system upgrade), uninstall it first then install it again:

wazo-plugind-cli -c "uninstall <namespace>/<name>"
wazo-plugind-cli -c "install <method> <source> [...]"
Reinstalling the same version

If the intent is to ensure the same version of the plugin is reinstalled, make sure the install command specifies an installation source that corresponds to a fixed version. For example, a git source should use a specific commit revision or tag as the --ref parameter, and not a mutable branch.

Upgrading plugins

There is no upgrade command. Upgrading a plugin manually can be done by installing a new version of the plugin with the same name. When installing a plugin that already exists, the version from the metadata of the installation target is compared with the version already installed, and the installation target is installed if the version differs, replacing the previous installation.

wazo-plugind-cli -c "install git https://github.com/myorg/myplugin --ref <new revision>"

Official plugins may be automatically upgraded during wazo-platform upgrades if new versions are made available.

Custom plugins (outside the "official" namespace) are not automatically upgraded.

Breaking changes between wazo-platform releases may require upgrading plugins to a compatible version.

Getting Help

For a complete list of available commands:

wazo-plugind-cli -c 'help'

For usage help on a specific command:

wazo-plugind-cli -c 'help <command>'

Plugin Maintenance After Upgrades

Plugins may need to be reinstalled or upgraded after upgrading the Wazo stack.

While official plugins may be automatically upgraded during Wazo-Platform upgrades, new wazo-platform releases may bring breaking changes to custom plugins. If a new compatible version of a plugin is made available, the plugin will need to be manually upgraded.

Wazo-Platform releases which involve a Debian distribution upgrade likely require upgrading or reinstalling plugins.

Non-official patch-based plugins require manually reinstalling after each Wazo-Platform upgrade, and are likely to break without proper maintenance work since they depend on a specific state of the Wazo-Platform code.

See Reinstalling and Upgrading instructions.

See version-specific upgrade notes for specific recommendations.

See Also