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