Configuring Plugins

About this module

Most applications will take advantage of the many Cypher libraries that are available for use.

At the end of this module, you will be able to:

Make a library (plugin) available to applications.
Confirm that a plugin is available.

Managing plugins

Some applications can use Neo4j out-of-the-box, but many applications require additional functionality that could be:

A library supported by Neo4j such as GraphQL or GRAPH ALGORITHMS.
A community-supported library, such as APOC.
Custom functionality that has been written by the developers of your application.

We refer to this additional functionality as a plugin that contains specific procedures. A plugin is typically specific to a particular release of Neo4j. In many cases, if you upgrade to a later version of Neo4j, you may also need to install a new, compatible plugin.

Retrieving available procedures

Here is an example of a script you can run to produce a file, Procedures.txt that contains the names of the procedures currently available for the Neo4j instance:

echo "CALL dbms.procedures() YIELD name;" |
    /usr/bin/cypher-shell -u neo4j -p <InstancePassword> --format plain >
    /home/ubuntu/report/DefaultProcedures.txt

This script calls a Neo4j built-in procedure, dbms.procedures() to return the name of each procedure available to the graph engine at runtime.

Procedures available to the Neo4j instance

Here is an example of a generated DefaultProcedures.txt file:

By default, the procedures available to the Neo4j instance are the built-in procedures that are named db.* and dbms.*.

Adding a plugin to the Neo4j instance

To add a plugin for use in a Neo4j instance, you must:

Obtain the .jar file.
Confirm that the .jar file you will use is compatible with the version of Neo4j that you are using.
Modify neo4j.conf.

For example, a plugin released for release 3.5 of Neo4j can be used by a Neo4j 3.5.3 instance, but the converse may not be true. You must check with the developers of the plugin for compatibility.

Some plugins require a configuration change. You must understand the configuration changes required for any plugin you are installing.

When you install Neo4j, the plugins directory contains a README.txt file that contains instructions related to sandboxing and whitelisting. These instructions may change in future releases of Neo4j.

Steps for adding a plugin

Install the plugin:
1. Download the plugin. If it is a zip file unzip the jar file.
2. Place the jar file in the plugins directory for the Neo4j instance.
3. Ensure that the jar is owned by neo4j and has execute permissions.
Configure the plugin:
1. Modify neo4j.conf to sandbox the procedures of the plugin.
2. Optionally whitelist the procedures that will be used by the application.
Restart the Neo4j instance.
Confirm the procedures of the plugin are available.

Sandboxing

Neo4j provides sandboxing to ensure that procedures do not inadvertently use insecure APIs. For example, when writing custom code it is possible to access Neo4j APIs that are not publicly supported, and these internal APIs are subject to change, without notice. Additionally, their use comes with the risk of performing insecure actions.

The sandboxing functionality limits the use of extensions to publicly supported APIs, which exclusively contain safe operations, or contain security checks.

Whitelisting

Neo4j whitelisting can be used to allow loading only a few extensions from a larger library.
The configuration setting dbms.security.procedures.whitelist is used to name certain procedures that must be available from a library.
It defines a comma-separated list of procedures that are to be loaded.
The list may contain fully-qualified procedure names and partial names with the wildcard *.

Example: The APOC plugin

APOC (Awesome Procedures on Cypher) is a very popular plugin used by many applications.

It contains almost 500 user-defined procedures that make accessing a graph incredibly efficient and much easier than writing your own Cypher statements to do the same thing.

You obtain the plugin from the APOC releases page:

Step 1: Install the APOC plugin

Here we download the .jar file to the plugins directory, change its permissions to execute, and change the owner to be neo4j:neo4j.

Step 2: Configure the APOC plugin

After you have placed the .jar file into the plugins directory, you must modify the configuration for the instance as described in the main page for APOC. As described on the APOC GitHub page, you have an option of either sandboxing or whitelisting the procedures of the plugin. How much of the APOC library is used by your application is determined by the developers so you use them as a resource for this type of configuration change.

Suppose we want to allow all APOC procedures to be available to this Neo4j instance. We would sandbox the plugin in the neo4j.conf file as follows where we specify:

dbms.security.procedures.unrestricted=apoc.*

Since APOC is large, you will most likely want to whitebox specific procedures so that only the procedures needed by the application are loaded into the Neo4j instance at runtime.

Step 3: Restart the Neo4j instance

And here we see the results after restarting the Neo4j instance:

You may see some warning messages, but you can ignore them as they represent some deprecated functionality of the APOC procedues.

Step 4: Confirm the plugin procedures are available

You can produce a report of all the procedures available in the Neo4j instance:

echo "CALL dbms.procedures() YIELD name;" |
       /usr/bin/cypher-shell -u neo4j -p <InstancePassword> --format plain >
        /home/ubuntu/report/APOCProcedures.txt

And here is some of what was produced in the report:

Before you begin

Make sure you have a terminal window open to your Docker Neo4j instance for this course.
Stop the Docker Neo4j instance.

Exercise steps:

In a Web browser, go to the GitHub repository for the APOC library.
Find the latest release of the library that is compatible with the version of Neo4j Enterprise Edition you are working with.
Download the already-built .jar file into the $HOME/docker-neo4j/neo4j/plugins directory.

In OS X and Linux:
```
cd $HOME/docker-neo4j/neo4j/plugins
```
```
curl -L <URL for the jar file> > <name of the jar file>
```
Make sure this .jar file has execute permissions.
Modify /etc/neo4j/neo4j.conf to allow (sandbox) all procedures of the APOC library.
```
dbms.security.procedures.unrestricted=apoc.*
```
Start the Neo4j instance.
View the log to ensure the instance started with no problems.

Using cypher-shell write a command to create the procedures.txt file that contains all of the procedures that are loaded for the Neo4j instance.

On OS X and Linux:

echo "CALL dbms.procedures YIELD name;" | docker exec --interactive neo4j bin/cypher-shell -u neo4j -p <your password> --format plain --database maindb > $HOME/docker-neo4j/neo4j/logs/reports/procedures.txt

On Windows:

echo CALL dbms.procedures YIELD name; | docker exec --interactive neo4j bin/cypher-shell -u neo4j -p <your password> --format plain --database maindb > %HOMEPATH%\docker-neo4j\neo4j\logs\reports\procedures.txt

Confirm that APOC procedures are loaded by examining the file produced.

Exercise summary

You have now configured a Neo4j instance so that applications that access the databases can use APOC library procedures.

Check your understanding

Question 1

What Cypher statement do you execute to get a list of all procedures available to the Neo4j instance?

Select the correct answer.

CALL getProcedures();
CALL dbms.procedures();
SHOW PROCEDURES;
:PROCEDURES

Question 2

After you have placed the .jar file for a plugin in the plugin directory for the Neo4j instance, what must you do before you restart the Neo4j instance?

Select the correct answers.

Change the .jar file to have execute permissions.
Ensure the .jar file is owned by neo4j:neo4j.
Add the plugin to dbms.security.procedures.unrestricted in neo4j.conf.
Specify which databases will use the plugin in neo4j.conf.

Question 3

Suppose a given plugin is very large, but your applications only use a few procedures of the plugin. What configuration change do you make to limit what procedures are loaded when the Neo4j instance starts?