7. Managing RDFox Servers

As explained in Section 4, each running RDFox instance contains a server object, which acts as a top-level container for all information stored in the instance. A server supports operations such as creating and deleting data stores, creating and deleting roles, and granting permissions to roles.

7.1. The Server Directory

To use any form of persistence (see persist-roles and persist-ds parameters below), the RDFox server must be configured with a directory in which the persisted content should be saved via the server-directory parameter. When configured, the server directory also serves as the default location for API logs (see api-log and related parameters below).

To protect the integrity of the server directory, RDFox attempts to acquire an exclusive lock over the directory at startup if role persistence is enabled. The lock is then held for the rest of the server’s lifetime. This prevents multiple running servers from using the same server directory concurrently. In addition, RDFox prohibits the use of data store persistence in the absence of role persistence. This ensures that data cannot be stored without matching access control policies.

7.2. Server Parameters

When a server is instantiated, it can be given a number of parameters that govern various aspects of the server’s operation. All parameters are specified as key-value pairs. When an RDFox instance is created from the command line, the server parameters are passed as arguments to the RDFox executable as described in Section 16.1. If an RDFox instance is started from Java, the server parameters can be specified as arguments to the tech.oxfordsemantic.jrdfox.client.ConnectionFactory.startLocalServer() method; please refer to the Javadoc for more information. In all cases, when the server-directory parameter is set, RDFox will load additional parameters from a file named parameters within the server directory if it exists. See Section 7.2.1 for details on the format of this file.

The following table describes all available server parameters.

Option

Value

Description

allowed-schemes-on-load

a string containing a space-separated list of URI schemes

Specifies a space-separated list of schemes that are allowed to be used in the SPARQL 1.1 LOAD update and to import from IRIs. The default value is https rdfox (rdfox is used to import TBoxReasoning as described in Section 6.6.6)

api-log

on or off

If the value is on, all API calls are recorded in a script that the shell can replay later. The default value is off. See Section 17.1 for more information.

api-log.directory

a string

Specifies the directory into which API logs will be written. Default is directory api-log within the configured server directory.

api-log.input-recording-limit

0, a positive integer or unlimited

Limits the amount of each input that is recorded during import operations as a part of an API log to the specified number of bytes. The value unlimited, which is the default, signifies that each input should be recorded in its entirety.

license-content

a string

Specifies the license content verbatim. This parameter is not set by default. See Section 2.4.3 for the precedence of license-related options.

license-file

a string

Specifies the path to the license key file to use. The default value is $HOME/.RDFox/RDFox.lic on Linux/Mac, and %LOCALAPPDATA%\RDFox\RDFox.lic on Windows. See Section 2.4.3 for the precedence of license-related options.

max-memory

an integer

Specifies the initial value for the maximum of memory (in MB) that the RDFox instance should use. The default is 0.9 times the installed memory.

num-threads

an integer

Specifies the initial number of threads that the system will use for tasks such as reasoning and importation. The default is the number of logical processors available on the machine.

persist-ds

file or off

If the value is file, data stores and their content will be incrementally saved (persisted) to files in the server directory. Must be off if persist-roles is off. Default value is off.

persist-roles

file or off

If the value is file, RDFox will persist roles, their privileges, and their memberships to a file in the server directory. Default value is off.

sandbox-directory

a string

Specifies the directory to which RDFox should restrict any file system access where the path is specified as part of an API call or shell command. The purpose of this feature is to prevent an attacker from probing the host’s filesystem using RDFox. The default value is the working directory of the RDFox process. Sandboxing of file access can be disable by setting this option to the empty string.

server-directory

a string

Specifies the server directory. See Section 7.1 for details.

7.2.1. The Server Parameters File

When an RDFox server is configured to use a server directory, it will inspect the directory for a file named parameters and, if the file is found, attempt to load server parameters from it. Parameter values specified explicitly by the user (for example via the command line arguments when using the RDFox executable) take precedence over values from the parameters file.

The parameters file must be encoded in UTF-8. Lines with # as the first non-whitespace character are ignored, as are empty lines. Each (parameter name, parameter value) pair must appear on a single line with optional leading whitespace followed by the parameter name, more whitespace, the value and optional trailing whitespace. Values that contain whitespace must be enclosed in double quotes ("). Double quotes within values must be escaped as \", newlines as \n, and backslashes as \\.

The following text block shows an example parameters file:

# Use 'file' persistence
persist-roles            file
persist-ds               file

# Enable loading of file: and https: URLs only
allowed-schemes-on-load  "file https"

# Restrict importing, exporting and reading of shell scripts to the ``/data`` directory
sandbox-directory        /data