18. Starting RDFox

The RDFox executable can be started in one of four modes: shell, daemon, sandbox or remote. The first three modes instantiate an RDFox server. The fourth mode, remote, does not create a server instance locally but instead connects to a remote instance whose endpoint is active. The syntax for starting in a server-instantiating mode is explained in the next section and the syntax for starting in remote mode is given in Section 18.2.

For details of how to instantiate and start the RDFox server within a Java process, see the Javadoc documentation for the tech.oxfordsemantic.jrdfox.client.ConnectionFactory class.

18.1. Instantiating a Server

RDFox processes that instantiate an RDFox Server can be started using the following command syntax:

RDFox [-<serverParameter> <value> ...] [-temp-role | [-role <role>] [-password <password>]]
      {daemon [<endpointParameter> <value> ...] | {shell | sandbox} [<root> [<command> ...]]}

The options specified as -<serverParameter> <value> pairs are used as parameters for the server instance.

A role name and password are required at startup if access control has not been initialized, if an instance of the shell is being created, or if both of these conditions hold. If both conditions hold, the -temp-role option can be set. This initializes access control with a temporary role which will be deleted when the shell closes, and creates an initial connection to the local server authenticated as that role. The -temp-role option is intended to be used to restore a transcribed RDFox instance. See transcribe for more information.

If -temp-role is not specified, but a role name and password are required, RDFox will look for the arguments -role <role> and -password <password>. If one or both of these options is missing, RDFox will next inspect the RDFOX_ROLE and RDFOX_PASSWORD environment variables respectively. If one or both of these variables remains unset after this, the behavior is mode-dependent; see the sections describing each mode below for details.

As these modes instantiate an RDFox server, a valid, in-date license key must be provided using one of the mechanisms described in Section 2.4.1.3.

Next, we look at each of the server-instantiating modes in detail.

18.1.1. shell

shell mode instantiates an RDFox server and shell together in a single process, with defaults suitable for production environments.

If the server-directory parameter is not explicitly specified in the command, shell mode sets it to a default location within the operating system user’s home directory ($HOME/.RDFox on Linux and macOS or $LOCALAPPDATA\RDFox\RDFox.lic on Windows).

If either or both of the role name or password is missing from the process command and environment, shell mode will prompt for the missing information to be given interactively.

The dir.root shell variable is set to the <root> value from the process command, if present, and any arguments thereafter are interpreted as shell commands or script names. The prompt is then returned for interactive input unless one of the supplied commands caused the shell to close. The endpoint and daemon shell commands enable the RDFox Endpoint to be started from any local shell, the former leaving the shell open, the latter closing it but leaving the process running. See Section 15 for full reference documentation for the RDFox shell.

Example: Initializing a Server Directory

Imagine that we wish to set up a new RDFox service whose users will access it exclusively via HTTP(S). In this example we will use shell mode to initialize the server directory so that it is ready to use with a background process (see example in documentation of daemon mode).

The storage provisioned for the server directory is mounted at /mnt/rdfox and we have already added a server parameters file specifying desired persistence options and other settings at path /mnt/rdfox/parameters. A script named initialize.rdfox, present in the working directory, contains commands to create and populate a data store and to create, and grant privileges to, the required roles. Finally, we have set a strong password into the RDFOX_PASSWORD environment variable. The initialization step can then be performed using:

RDFox -server-directory /mnt/rdfox -role server-admin shell . "set on-error stop" intialize.rdfox quit

As we have provided both a name (via the -role argument) and password (via the RDFOX_PASSWORD environment variable) for the first server role, and because we have specified quit as the final shell command, the process will run and exit without prompting for input. To check whether the initialization was performed successfully we can read the output and/or examine the return code for the process. The first of our supplied shell commands ("set on-error stop") ensures that any errors caused by commands in the initialize.rdfox script cause the process to exit with a non-zero return code indicating failure.

18.1.2. sandbox

sandbox mode instantiates the RDFox server and shell together in a single process with defaults that are suitable for local experimentation and development. The use of sandbox mode in production is discouraged for security reasons even though it is possible to achieve a secure setup in this mode by overriding its default behaviour.

By default, sandbox mode specifies no server-directory server parameter and therefore uses no persistence. The sandbox-directory server parameter is set to the empty string by default, disabling file system sandboxing of the core APIs. Finally, the allowed-schemes-on-load server parameters is defaulted to file http https rdfox to allow loading by URIs belonging to any of the supported schemes. See Section 4.3 for details of the above server parameters.

The value guest is used as a default for both the name and the password of the first role to avoid the the need for enter these values and to ensure that anonymous requests to the RDFox endpoint (if started) have full control over the server (see Section 19.3 for more information).

The dir.root shell variable is set to the <root> value from the process command, if present, and any arguments thereafter are interpreted as shell commands or script names. The prompt is then returned for interactive input unless one of the supplied commands caused the shell to close. The endpoint and daemon shell commands enable the RDFox Endpoint to be started from any local shell, the former leaving the shell open, the latter closing it but leaving the process running. See Section 15 for full reference documentation for the RDFox shell.

Example: Quick Start

The fastest way to experiment with RDFox’s functionality is to run:

RDFox sandbox

If desired, the endpoint can then be started with:

endpoint start

giving access to the REST API and the RDFox Console.

18.1.3. daemon

daemon mode instantiates the RDFox server and RDFox endpoint with defaults that are suitable for experimentation and for running as a background process or OS-managed service.

If the server-directory parameter is not explicitly specified in the command, daemon mode sets it to the same default location as shell mode.

If access control is not initialized and either the name or password for the first server role is absent from the command line and environment, daemon mode will exit with a message explaining that it would be impossible to login since there are no roles. In most circumstances, it is advisable to initialize access control within a server directory using shell mode prior to launching a daemon mode process using the same server directory. This avoids the need for a plaintext password in the command or environment of the latter.

The <endpointParameter> <value> key-value pairs from the process command are interpreted as parameters for the RDFox Endpoint.

Example: Launching a Daemon

Following on from the example in Section 18.1.1 we can start the long-lived RDFox process that will provide service via HTTP(S) as follows:

RDFox -server-directory /mnt/rdfox daemon request-logger elf

Here we have specified that each request should be logged to standard output using the extended log format (see Section 19.2 for details).

18.2. Remote Shell Client

The following command syntax can be used to connect using shell to an RDFox process running on a different server:

RDFox [-role <role>] [-password <password>] remote <server-url> [<command> ...]

The resulting process will call the remote shell API of the server at <server-url> to instantiate a remote shell instance, which will be used to run any commands supplied on the command line, and then prompt for further commands to run.

A role name and password are required at startup. RDFox will first look for the arguments -role <role> and -password <password>. If one or both of these options is missing, RDFox will next inspect the RDFOX_ROLE and RDFOX_PASSWORD environment variables respectively. If after this one or both variables remain unset, RDFox will prompt for the missing information.

When invoked from the remote shell, commands will operate in exactly the same way as if they were invoked from the local shell (shell and sandbox modes) save for the exceptions documented in Section 16.18.1.1. Interruptible operations may be interrupted with Ctrl-C just as in local shells.

File paths embedded within commands are always interpreted with respect to the server’s file system. The remote shell client does not provide any way of using the client’s file system (unless the client is running on the same host as the server).

As remote mode does not create an RDFox server instance, no license key is required.

Example: connecting to a remote server

To connect to a server reachable at http://localhost:12110, run:

RDFox remote http://localhost:12110