19. RDFox Endpoint¶
19.1. Starting and Stopping the Endpoint¶
The endpoint can be started in the following ways:
By launching the RDFox process in
daemonmode (see Section 18).
endpoint startwithin the RDFox shell (see Section 15.2.17). When started in this manner, the endpoint accesses the same RDFox server as the shell, so the effects of any commands that affect the state of the server (e.g.,
dstore create) will be immediately visible on the endpoint.
daemonwithin the RDFox shell (see Section 15.2.11).
The endpoint can be stopped in the shell by issuing
endpoint stop. Processes
daemon mode (where there is no active instance of the shell) can
be stopped by sending them a
SIGINT (for example with Ctrl-C) or
19.2. Endpoint Parameters¶
The configuration of the endpoint is determined by the parameters below. It is not possible to modify the configuration of the endpoint once it is listening however, in the shell, the endpoint can be stopped and restarted with new parameter values.
portdetermines the port at which the endpoint is started. The port can be specified as a verbatim port number or as a TCP service name. The default is
12110. For legacy reasons, the port can also be specified using
service-name; moreover, if both options are present, then
num-threadsdetermines the number of threads that endpoint will use to process RESTful requests. The default value is one less than the number of logical processors of the machine on which RDFox is run.
channeldetermines the connection type that the endpoint should use.
unsecuremeans the endpoint will listen for HTTP connections (only). This is the default value.
sslmeans the endpoint will listen for HTTPS connections (only). This option requires the OpenSSL package. See also the
The following parameters determine the SSL/TLS configuration for the endpoint.
credentialsspecifies the server certificate and private key, and the intermediate certificates as a verbatim string in PEM format. The string must contain the server’s private key, the server’s certificate, and zero or more intermediate certificates. For example, this file could look as follows:
-----BEGIN RSA PRIVATE KEY----- ... server key ... -----END RSA PRIVATE KEY----- -----BEGIN CERTIFICATE----- ... server certificate ... -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- ... 1st intermediate certificate ... -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- ... 2st intermediate certificate ... -----END CERTIFICATE-----
credentials-filespecifies the name of the file whose content contains the credentials. The file content must have the same format as the
credentials-namespecifies the comma-separated list of names of items in the system’s keystore. The first name must identify a certificate and a private key, which are used as a main identity of the server. The remaining names identify intermediate certificates. This option is available only on macOS, where the keystore is the system’s keychain.
credentials-passphraseprovides the passphrase that can be used to unlock the credentials in case they are encrypted. This parameter is optional.
min-secure-protocoldetermines the minimum protocol version that the server should use. The allowed values are
tls13. The default value is
openSSL.crypto-libspecifies the string to use to search for the
crytpolibrary from OpenSSL. Default is
libcrypto.1.1.dylibon macOS, and
openSSL.ssl-libspecifies the string to use to search for the
ssllibrary from OpenSSL. Default is
libssl.1.1.dylibon macOS, and
channel-timeoutdetermines the length of time that the endpoint will wait for I/O while servicing HTTP(S) requests. That is, if the endpoint tries to read from or write to the TCP connection, the respective I/O will wait for for the specified duration before giving up. This option ensures endpoint resilience in the face of slow or buggy HTTP(S) clients. See Section 19.2.1 for the accepted values for this parameter. The
unlimitedsetting may be used but should be reserved for those cases where there are valid reasons for I/O operations to take a long time and clients are known to be correct. The default value is
max-idle-connectionsdetermines the maximum number of connections to the server that can be idle at any point in time. Once this limit is exceeded, RDFox endpoint will close all idle connections (even those that have been idle for less than
connection-keep-alive-time) in order to free resources and thus provide uninterrupted service to users. For this option to be effective, it should be set to some value lower than the maximum number of file descriptors for the RDFox process. On Window, the default value for this parameter is 1024. On Linux and macOS, the default value is set to 90% of the maximum number of file descriptors for the server process.
connection-keep-alive-timedetermines the maximum time in seconds that an HTTP connection will be kept open between requests. That is, if a client opens a TCP connection to the endpoint and makes a request, the server will wait for the specified amount of time to receive another request on this connection; if no request is issued in the specified time, the server will close the connection. See Section 19.2.1 for the accepted values for this parameter. The
unlimitedsetting may not be used. The value of
0means that the server should close the TCP connection after every request. The default value is
listening-backlogdetermines the TCP listening backlog for the socket accepting the connection. The default value is 10.
send-bufferdetermine the sizes in bytes of the receive and send buffers for the sockets servicing the requests. The default values are zero, which means that the system will determine the buffer sizes depending on the properties of the connection. For more information, please refer to the SO_RCVBUF and SO_SNDBUF socket options.
object-keep-alive-timespecifies the time in seconds that the endpoint will keep cached cursors, connections or shells between requests. During its operation, the endpoint retains certain objects between requests either for performance reasons (e.g., the endpoint may cache cursors of partially evaluated queries) or to ensure its operation (e.g., the endpoint will maintain named server and data store connections). In order to prevent these objects from accumulating indefinitely, the endpoint will delete each object after it has not been used for the specified amount of time. See Section 19.2.1 for the accepted values for this parameter. The
unlimitedsetting may not be used. The default value for this parameter is
access-control-allow-originconfigures the RDFox endpoint for Cross-Origin Resource Sharing (CORS). When this option is set, RDFox will include, in response to CORS requests, all the headers necessary to allow cross-origin usage of the REST API by the specified origin or origins. The value
*can be set to allow use of the REST API by any origin, however such usage will be restricted to anonymous requests (see Section 19.3) due to the CORS specification’s rules on credentials (see this section of the CORS specification). If the value is not set to
*, it must be set to a single origin such as
http://localhost:8080to allow requests from just that origin. When this option is unset (the default), RDFox will not add any CORS headers to its responses.
protocoldetermines which network layer protocol the endpoint will use.
IPv4means the endpoint will use Internet Protocol version 4.
IPv6means the endpoint will use Internet Protocol version 6.
IPv6-v4means the endpoint will use Internet Protocol version 6 if possible or Internet Protocol version 4 if not. This is the default value.
The following parameters determine the configuration for HTTP request logging (see also Section 20.2).
request-loggerdetermines how each serviced HTTP request is logged. All logging goes to standard output.
nonedisables request logging. This is the default value.
clfenables request logging using the Common Log Format.
elfenables request logging using the Extended Log Format. The exact content of each log entry is determined by the
elf-logger-fieldsparameter. Each log entry is limited to 10 KiB. Where an entry would exceed this limit, the elided fields are indicated with
elf-logger-fieldsdetermines which fields are logged by the extended log format logger. This parameter has no effect unless
request-loggeris set to
elf. The value for this parameter must be a space-delimited list of the following field identifiers:
x-socket-exception. The identifier
x-role-namespecifies the role name with which the request was made. The identifier
x-socket-exceptionspecifies the textual description of any exception raised when the endpoint attempts to accept a socket connection. All other identifiers have the meanings defined in the draft specification. The default value for this parameter is
date time cs-method cs-uri-stem sc-status sc-bytes time-taken.
The following parameters determine the configuration for time limits on the evaluation of SPARQL queries.
query-time-limitdetermines the maximum time in seconds that a request for query evaluation can take; if a query request is not completed in that time, query evaluation will be stopped. See Section 19.2.1 for the accepted values for this parameter. The
unlimitedsetting may be used. The default value is
allow-query-time-limit-overrideis a Boolean value specifying whether a query request can override the time limit on query evaluation. If this option is set to
yes, then each query evaluation request can use the
Query-Time-Limitheader to specify the query time limit to be used for the current request. The value of the
Query-Time-Limitheader follows the same syntax as the
query-time-limitendpoint parameter. The default value is
19.2.1. Specifying Durations¶
Several endpoint parameters control waiting times between actions taken by the
endpoint. To specify a finite waiting time, the associated parameter value must
contain a non-negative integer followed by an optional space and an optional
unit specifier. The accepted unit specifiers are
s (the default) and
ms. To specify an infinite waiting time the value can be set to the string
unlimited although this is not accepted for all duration parameter names.
19.3. Anonymous Requests and the
Upon receiving a REST request with no
Authorization header, the RDFox
endpoint will attempt to authenticate as role
guest. If this authentication
succeeds, the endpoint will then continue processing the request using the
resulting connection. The level of access to an RDFox
server available via anonymous (i.e. unauthenticated) requests can therefore be
controlled by granting the appropriate privileges to the
guest role or, in
the case that all requests should be authenticated, ensuring that
not one of the server’s roles.
For more details on access control, see Section 12.