22.1. Managing plug-ins and extensions

22.1.1. Automatic installation wizard
22.1.2. Manual plug-in registration
22.1.3. BASE version 1 plug-ins
22.1.4. Installing the X-JSP compiler
22.1.5. Disable/enable plug-ins and extensions
22.1.6. Plug-in permissions
[Important] Changes since BASE 2

The plug-in and extensions installation has changed since BASE 2. The major changes are:

  • The main JAR file must be installed in the directory specified by the plugins.dir setting in base.config. Subdirectories are not allowed. This applies to both plug-ins and extensions. The WEB-INF/extensions is not used for extensions anymore.

  • A package must be installed as a whole. It is no longer possible to only select some of the plug-ins to install. If neccessary, the administrator can always disable plug-ins that is not wanted.

The first step is to install the actual code on the web server. The recommendation to developers is to ship the entire package as a single JAR file. If everything is JAVA based this should not be a problem. A common exception is that configuration files should be installed (and configured) separately. Always read the installation instructions for the package you are installing. The rest of the instructions in this section assume that the plug-in/extensions comes as a single JAR file.

[Note] Make sure the extensions folder is writable by Tomcat

The package you are installing may include resources such as HTML files, JSP scripts, images, etc. that needs to be extracted to the web application path before they can be used. This extraction is automatically done by the installation wizard, but you have to make sure that the user account Tomcat is running as has permission to create (and delete) new files in the <base-dir>/www/extensions directory.

So, the first step should be simple. Just put the JAR file in the dedicated plug-ins directory. This is the directory that is specified in the plugins.dir setting in base.config.

[Important] Content security policy

Since BASE 3.3 the default configuration specify a setting that tell web browsers to not execute code (including JavaScript) that is considered unsafe. Older extensions may not adhere to the restrictions implied by this and may thus not work unless the configured Content security policy is relaxed a bit. The extension installation wizard will try to detect if a plug-in violates the policy and display a warning message. If you see the warning please read Section E.1, “Content security policy” for more information.

22.1.1. Automatic installation wizard

When the plug-in/extensions package is installed on the server you must register it with BASE. Go to AdministratePlug-ins & extensionsOverview.

Figure 22.1. Installed extensions & plug-ins

Installed extensions & plug-ins

The left-hand side of the screen shows a tree with all installed plug-ins and extensions, sorted by extension point and by file. Use the + and - icons to expand and collapse parts of the tree. Click on an item in the tree to display detailed information about it on the right-hand side of the screen. Click on the Install/uninstall button to start the installation wizard (which can also be used for uninstallation).

Figure 22.2. Extensions and plug-ins installation wizard

Extensions and plug-ins installation wizard

This wizard can be used for both installing, re-installing and un-installing plug-in and extension packages. The first dialog shows a list with all currently installed packages as well as any new packages that has been found on the server. The list includes the name of the JAR file, the current status and some information provided by the author of the package. There are also three columns Install, Uninstall and Ignore which may or may not have a checkbox in them. For new packages there should be a checkbox in the install column that is already checked. Already installed packages can either be re-installed or uninstalled by checking the appropriate checkbox. If there is a problem with a package an error message is displayed and neither installation or uninstallation is possible.

The Ignore column can be used to tell the wizard to ignore the selected file from now on. Ignored files are moved to a separate section at the bottom of the installation wizard and you will not be asked about installing them every time you run the wizard. Ignored files can either be brought back to the regular flow with the Stop ignore option or directly installed with the Install button.

Click on Next to perform the selected actions. The next dialog should display a summary with the installation results. Hopefully everything was succeessful. Close the dialog and refresh the overview tree to see the changes.

[Note] Note

Uninstalling a package doesn't remove the plug-in definitions from BASE nor does it remove the JAR file from the server. This is because there may be jobs and other items referencing the plug-ins. The plug-ins are only marked as disabled and it is up to the administrator to actually delete them if it is possible.

Figure 22.3. Extensions and plug-ins installation results

Extensions and plug-ins installation results

22.1.2. Manual plug-in registration

Manual installation of a plug-in should almost never be neccessary. One exception is that developers may want to do this as a first step before everything has been properly packaged. Another exception is plug-ins developed for BASE 2 that doesn't support the automatic installation procedure. If the old plug-in still works API-wise in BASE 3, manual installation can be used to install it. Repackaging such a plug-in is however not difficult so we recommend that the plug-in author is asked to provide an updated version.

To perform a manual installation the plug-in's JAR file must be located in the the directory specified by the plugins.dir setting in base.config. Subdirectories are not allowed. This is a change since BASE 2 were plug-ins could be installed almost anywhere. When the JAR file is in place, go to AdministratePlug-ins & extensionsPlug-in definitions and click on the New button.

Figure 22.4. Manually installing a plug-in

Manually installing a plug-in

Name

The name of the plug-in. This name is set automatically by the plug-in and cannot be changed.

Class

The full Java class name of the plug-in.

JAR file

The name of the JAR file on the web server. The JAR file must be installed in the directory specified by the plugins.dir setting in base.config If left empty the plug-in must be on the web server's class path (not recommended).

Max memory

The maximum amount of memory the plug-in may use. This setting only applies when the plug-in is executed with a job agent. If the internal job queue is used this setting has no effect and the plug-in may use as much memory as it likes. See Section 21.3.4, “Configuring the job agent” for more information.

Trusted

If the plug-in is trusted enough to be executed in an unprotected environment. This setting has currently no effect since BASE cannot run in a protected environment. When this becomes implemented in the future a no value will apply security restrictions to plug-ins similar to those a web browser put on applets. For example, the plug-in is not allowed to access the file system, open ports, shut down the server, and a lot of other nasty things.

Allow immediate execution

If the plug-in is allowed to bypass the job queue and be executed immediately.

  • No: The plug-in must always use the job queue.

  • Yes: The plug-in is allowed to bypass the job queue. This also means that the plug-in always executes on the web server, job agents are not used. This setting is mainly useful for export plug-ins that needs to support immediate download of the exported data. See the section called “Immediate download of the exported data”.

    [Note] Note
    If a plug-in should be executed immediately or not is always decided by the plug-in. BASE will never give the users a choice.
  • Auto: BASE will allow export plug-ins to execute immediately, and deny all other types of plug-ins. This alternative is only available when registering a new plug-in.

Click on Save to finish the registration or on Cancel to abort.

22.1.3. BASE version 1 plug-ins

BASE version 1 plug-ins are supported through the use of the Base1PluginExecuter plug-in. This is itself a plug-in and BASE version 1 plug-ins are added as configurations to this plug-in (cf. Section 22.2, “Plug-in configurations”). To install a BASE version 1 plug-in follow these instructions:

  1. Install the BASE version 1 plug-in executable and any other files needed by it on the BASE server. Check the documentation for the plug-in for information about what is needed.

  2. Upload the *.base file for the BASE version 1 plug-in. If you cannot find the file, you can let your BASE version 1 server create one for you. In your BASE version 1 installation go to Analyze dataPlug-ins and use the Export function. This will create a configuration file for your BASE version 1 plug-in that you can upload to your new BASE server.

  3. Create a new plug-in configuration using, for example, the New configuration button in single-item view for the Base1PluginExecuter plug-in.

  4. Start the configuration wizard and select parameters:

    • File: The *.base file describing the BASE version 1 plug-in. This can be left empty for manual configuration, but in reality it is only usable for tweaking an existing configuration that has been created from a file in the first place.

    • Plugin executables path: The path to the executable program that was installed in the first step.

    • Source intensities: Select if the plug-in can work with regular or logged data (or both).

    • Resulting intensities: Select if the plug-in generates regular or logged data.

    Click Next to finish the wizard.

  5. To check that the new plug-in works correctly, you need to have an experiment with some data. Go to the single-item view for a bioassay set and click on the Run analysis button. Select the Base1PluginExecuter plug-in. The list of configurations should include the newly installed plug-in. Select it and click on Next.

  6. This will enter regular plug-in execution wizard and you will have to enter parameters needed by the plug-in.

22.1.4. Installing the X-JSP compiler

Some extensions may want to use custom JSP files that also uses classes that are stored in the extension's JAR file. The problem with this is that Tomcat usually doesn't know to look for classes in the plugins.dir directory. To solve this problem BASE ships with a X-JSP compiler that can do this. This compiler has been mapped to files with a .xjsp extension, which are just regular JSP files with a different extension.

The X-JSP compiler must be installed into Tomcat's internal library folder ($CATALINA_HOME/lib) since this is the only place where Tomcat look for compilers. The installation is easy. Simply copy <base-dir>/bin/jar/base-xjsp-compiler-3.x.jar to $CATALINA_HOME/lib and restart Tomcat.

[Note] X-JSP is experimental

This is an experimental feature that depends on internal functionality in Tomcat. It may or may not work with future versions of Tomcat. The compiler will most likely not work with other servlet containers.

22.1.5. Disable/enable plug-ins and extensions

It is possible to disable specific extensions, extension point and or a plug-in without uninstalling the XML or JAR file. When you click on an item in the tree on the left-hand side of the screen a lot of detailed information about it will show up on the right-hand side. The right-hand side usually has a Disable or Disable all button in the toolbar. Click on that button to disable the plug-in, extension or all extensions for an extension point. The button will change to Enable or Enable all which lets you enable the extensions and plug-ins again.

22.1.6. Plug-in permissions

When a plug-in is executed the default is to give it the same permissions as the user that started it. This can be seen as a security risk if the plug-in is not trusted, or if someone manages to replace the plug-in code with their own code. A malicious plug-in can, for example, delete the entire database if invoked by the root user.

To limit this problem it is possible to tune the permissions for a plug-in so that it only has permission to do things that it is supposed to do. For example, a plug-in that import reporters may only need permission to update and create new reporters and nothing else.

To enable the permission system for a plug-in go the edit view of the plug-in and select the Permissions tab.

Figure 22.5. Setting permissions on a plug-in

Setting permissions on a plug-in

Use permissions

Select if the plug-in should use the permission system or not. If no is selected, the rest of the form is disabled.

Item types

The list contains all item types found in BASE that can have permissions set on them. The list is more or less the same as the permission list for roles. See the section called “Permissions”.

Always grant

The selected permissions will always be granted to the plug-in no matter if the logged in user had the permission to begin with or not. This makes it possible to develop a plug-in that allows users to do things that they are normally not allowed to do. The reporter importer is for example allowed to create and use reporter types.

Always deny

The selected permissions will always be denied to the plug-in no matter if the logged in user had the permission to begin with or not. The default is to always deny all permissions. Permissions that are not always denied and not always granted uses permissions from the logged in user.

Requested by plug-in

To make it easier for the server administrator to assign permissions, the plug-in developer can let the plug-in include a list of permissions that are needed. Plug-in developers are advised to only include the minimal set of permissions that are required for the plug-in to function. Click on the Use requested permissions button to give the plug-in the requested permissions.