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