Server Configuration
This page discusses configuring the Stardog server. Configuring a Stardog database is discussed in detail in the Database Configuration section.
Page Contents
Configuring Temporary (“Scratch”) Space
Stardog uses the value of the JVM argument java.io.tmpdir
to write temporary files for many different operations. If you want to configure temp space to use a particular disk volume or partition, use the java.io.tmpdir
JVM argument on Stardog startup.
Bad (or, at least, weird) things are guaranteed to happen if this part of the filesystem runs out of (or even low on) free disk space. Stardog will delete temporary files when they’re no longer needed. But Stardog admins should configure their monitoring systems to make sure that free disk space is always available, both on java.io.tmpdir
and on the disk volume that hosts STARDOG_HOME
. This is equally true, when using Stardog HA Cluster, of Zookeeper’s access to free disk space. Bad things happen to the Stardog Cluster if Zookeeper cannot write to disk.
stardog.properties
The main configuration file for Stardog is the stardog.properties
file, which is a Java properties file. This file contains configuration properties to configure Stardog’s global behavior. The stardog.properties
file should be placed into the $STARDOG_HOME
directory to take effect.
To specify another location for the stardog.properties
file, you can set the STARDOG_PROPERTIES
environment variable.
Example
An example stardog.properties
file is provided in our Stardog examples Github repository.
Updatable Properties
For most server properties to take effect in a running Stardog Server, it is necessary to restart it. However, certain properties (e.g. some of the LDAP properties) are updatable and can be mutated without a restart using the property-set
admin command, which updates a property (on all Stardog servers in a cluster) and saves the change to the stardog.properties
file. Use the property-get
command to see a list of all set (updatable and otherwise) server properties.
Configuration Options
The properties described in this section control the global behavior of the Stardog Server.
You’ll observe each server property has a field “Overridable”. Overridable, in this context, means you can set this option at the database level overriding the value set for the server. This isn’t relevant for most properties, but can be useful for setting query related properties for example. See the Database Configuration section for details on setting and configuring database options.
Query Answering
Properties to configure queries at the server level:
query.all.graphs
- Default
false
- Description
- If a SPARQL query does not use
FROM
orFROM NAMED
keywords, this option will define what data it is evaluated against; iftrue
, it will run over the default graph and the union of all named graphs; iffalse
(the default), it will run only over the default graph. - Overridable
- true
query.timeout
- Default
5m
- Description
- Sets the upper bound for query execution time that's inherited by all databases unless explicitly overridden by a database-specific timeout value in database options. The following unit suffixes are available: "ms" for milliseconds, "s" for seconds, "m" for minutes, and "h" for hours.
- Overridable
- true
query..update.timeout
- Default
10h
- Description
- Sets the upper bound for SPARQL Update query execution time that's inherited by all databases unless explicitly overridden by a database-specific timeout value in database options. The following unit suffixes are available: "ms" for milliseconds, "s" for seconds, "m" for minutes, and "h" for hours.
- Overridable
- true
query.timeout.override.enabled
- Default
true
- Description
- When enabled, users are able to override the default timeout value. When disabled, queries must respect the value set in
query.timeout
. - Overridable
- false
Connection Configuration
database.connection.timeout
- Default
10m
- Description
- The amount of time a connection to the database can be open, but inactive, before being automatically closed to reclaim the resources. The timeout values specified in the property file should be a positive integer followed by either letter 'h' (for hours), letter 'm' (for minutes), letter 's' (for seconds), or letters 'ms' (for milliseconds). Example intervals:
1h
for 1 hour,5m
for 5 minutes,90s
for 90 seconds,500ms
for 500 milliseconds.
NOTE: setting a short timeout can have adverse results, especially if updates are being performed without commit changes to the server, closing the connection prematurely while using it. - Overridable
- true
Backups
Server properties for backing up the Stardog server and databases.
backup.dir
- Default
$STARDOG_HOME/.backup
- Description
- The top level directory which is to be used by Stardog for storing backups. By default, this is the
.backup
directory in your$STARDOG_HOME
, but you can use this property to specify a different location for backups. Within this directory, backups are stored by database, and for each database, in date-versioned directories. - Overridable
- false
backup.location
- Default
- Description
- This property can be set if you need to specify a backup location outside of
$STARDOG_HOME
(e.g. a network mount). A default S3 or GCP backup location can also be specified here. See the sections Backup to S3 and Backup to GCP for more info. - Overridable
- false
backup.keep.last.number.backups
- Default
4
- Description
- Controls how many server backups will be retained by Stardog. See the Server Backup & Restore section for more details.
- Overridable
- false
backup.autorestore.dbnames
- Default
- Description
- A regular expression that matches the names of the databases to automatically restore on startup, eg:
.*
for every database. See Automatic Restore for more information. - Overridable
- false
backup.autorestore.onfailure
- Default
false
- Description
- A boolean value that determines if all databases which failed to load should be automatically restored from a backup location. See Automatic Restore for more information.
- Overridable
- false
Memory
Server properties to configure memory in Stardog.
memory.management
- Default
NATIVE
- Description
- To disable custom memory management and have Stardog run all queries on heap you can set this property to
JVM
. Please consult the memory management section of the docs to learn more about how Stardog manages memory and to see if modifying this property is right for you. - Overridable
- false
memory.mode
- Default
default
- Description
- Stardog defines three standard memory consumption modes to allow users to configure how memory should be distributed based on the usage scenario -
read_optimized
,write_optimized
,bulk_load
. Please consult the memory management section of the docs to learn more about these options. - Overridable
- false
memory.managed.block.size
- Default
32K
- Description
- Size of blocks allocated by the memory management subsystem. Smaller blocks may improve memory utilization, but increase overhead.
- Overridable
- false
memory.managed.allocate.immediately
- Default
true
- Description
- Immediately allocate the maximum number of memory blocks on server start.
- Overridable
- false
spilling.dir
- Default
$STARDOG_HOME/.spilling
- Description
- When Stardog cannot handle an operation (e.g. a query) in memory, it spills data to disk. This property determines the directory these operations will spill data to. By default, data will be spilled to the
.spilling
directory inside$STARDOG_HOME
. It may make sense to set this to another disk to minimize disk contention. - Overridable
- false
spilling.max.file.length
- Default
10G
- Description
- When Stardog cannot handle an operation in memory, it spills data to disk. This property controls the maximum size of a single file Stardog will spill data to. A query can spill to multiple files and each are bound by the value set here. NOTE: this will only take effect if the server property,
memory.management
, is also enabled, which Stardog does by default. - Overridable
- false
Geospatial
Server properties to modify Stardog’s geospatial support.
spatial.use.jts
- Default
false
- Description
- Enable support for JTS in the geospatial module.
- Overridable
- false
Cluster
Server properties for Stardog Cluster
pack.enabled
- Default
false
- Description
- Flag to enable the cluster, without this flag set, the rest of the cluster properties have no effect
- Overridable
- false
pack.node.address
- Default
InetAddress.getLocalhost().getAddress()
- Description
- The local address of the node. The default value of this property is
InetAddress.getLocalhost().getAddress()
, which should work for many deployments. However if you’re using an atypical network topology and the default value is not correct, you can provide a value for this property. If provided it should be unique for each Stardog node. - Overridable
- false
pack.zookeeper.address
- Default
- Description
- a ZooKeeper connection string where cluster stores its state.
- Overridable
- false
pack.zookeeper.auth
- Default
admin:admin
- Description
- When starting Stardog instances for the cluster, unlike single server mode, you need to provide the credentials of a superuser that will be used for securing the data stored in ZooKeeper and for intra-cluster communication. Each node should be started with the same superuser credentials. By default, Stardog comes with a superuser
admin
that has password "admin" and that is the default credentials used by theserver start
CLI command. For a secure installation of Stardog cluster you should change these credentials by specifying this property and restart the cluster with new credentials. - Overridable
- false
pack.connection.timeout
- Default
- The default value is the default connection timeout for ZooKeeper.
- Description
- Specifies the max time that Stardog waits to establish a connection to ZooKeeper. See Connection/Session Timeouts for more information.
- Overridable
- false
pack.session.timeout
- Default
- The default value is the default session timeout for ZooKeeper.
- Description
- Specifies the max time that Stardog nodes wait to establish a session with the Zookeeper cluster. See Connection/Session Timeouts for more information.
- Overridable
- false
Security
Properties used to configure Security in Stardog:
password.length.min
- Default
4
- Description
- Sets the password policy for the minimum length of user passwords.
- Overridable
- false
password.length.max
- Default
1024
- Description
- Sets the password policy for the maximum length of user passwords.
- Overridable
- false
password.regex
- Default
[\w@#$%!&]+
- Description
- Sets the password policy of accepted chars in user passwords, via a Java regular expression.
- Overridable
- false
security.named.graphs
- Default
false
- Description
- Sets named graph security on globally.
- Overridable
- true
SSL
Properties used to configure Stardog to use SSL:
javax.net.ssl.keyStorePassword
- Default
- Description
- The password for the keystore.
- Overridable
- false
javax.net.ssl.keyStore
- Default
- Description
- If this is not specified,
$STARDOG_home/keystore
is checked, and then, the standard JVM locations within$JAVA_HOME
. Example:/path/to/the/keystore
- Overridable
- false
javax.net.ssl.keyStoreType
- Default
jks
- Description
- If the keystore is of a different type than the default (
jks
), you can specify its type. Example:pkcs12
- Overridable
- false
LDAP
LDAP and the server properties required for LDAP configuration are described at length in its dedicated chapter.
Kerberos
Kerberos and the server properties required for Kerberos configuration are described at length in its dedicated chapter.
Logging
This section contains configuration properties for logging in Stardog. See the section on Server Logging for further information on configuring logging.
Access Logging
The server properties used for Access Logging are listed below:
logging.access.enabled
- Default
false
- Description
- Access log is disabled by default and should be enabled explicitly by setting this to
true
- Overridable
- false
logging.access.type
- Default
binary
- Description
- The type of access log. There are two allowed values
text
andbinary
, both based on Protobuf. Intext
logs, entries are serialized as key-value pairs in plain text and log entries are delimited by the ASCII Start of Text and ASCII End of Text bytes. Inbinary
logs, entries are written as size delimited protobuf binary messages. - Overridable
- false
logging.access.file
- Default
${STARDOG_HOME}/access.log
- Description
- File name for the access log. By default, access log is saved as a file named
access.log
inside the${STARDOG_HOME}
directory. Optionally an absolute path can be provided to save the file in a different directory. - Overridable
- false
logging.access.rotation.type
- Default
- Description
- It is possible to define a file rotation strategy so that access log entries will be split into multiple files. One possibility is to define a limit on file size and start a new file when the size limit is reached. Specify
size
as the value for this option. Alternately, log files can be rotated at fixed time intervals by specifying a value oftime
. - Overridable
- false
logging.access.rotation.limit
- Default
- Description
- If you've set
logging.access.rotation.type=size
you can specify the size limit in bytes to determine the rotation frequency of the access log. Example:1000000
. The file that exceeds the limit will be renamed with a unique suffix and all the subsequent entries will be added to the newly created file. - Overridable
- false
logging.access.rotation.interval
- Default
- Description
- If you've set
logging.access.rotation.type=time
you can specify the log to be rotated at fixed time intervals. The interval value should be a positive integer followed by either letter 'd' (for days) or letter 'h' (for hours). Examples intervals are7d
for weekly logs,1d
for daily logs,12h
for two log files per day, and1h
for hourly logs. The file that exceeds the interval will be renamed with a unique suffix and all the subsequent entries will be added to the newly created file - Overridable
- false
Audit Logging
The server properties used for Audit Logging are listed below:
logging.audit.enabled
- Default
false
- Description
- Audit log is disabled by default and should be enabled explicitly by setting this to
true
- Overridable
- false
logging.audit.type
- Default
binary
- Description
- The type of audit log. There are two allowed values
text
andbinary
, both based on Protobuf. Intext
logs, entries are serialized as key-value pairs in plain text and log entries are delimited by the ASCII Start of Text and ASCII End of Text bytes. Inbinary
logs, entries are written as size delimited protobuf binary messages. - Overridable
- false
logging.audit.file
- Default
${STARDOG_HOME}/audit.log
- Description
- File name for the audit log. By default, audit log is saved as a file named
audit.log
inside the${STARDOG_HOME}
directory. Optionally an absolute path can be provided to save the file in a different directory. - Overridable
- false
logging.audit.rotation.type
- Default
- Description
- It is possible to define a file rotation strategy so that audit log entries will be split into multiple files. One possibility is to define a limit on file size and start a new file when the size limit is reached. Specify
size
as the value for this option. Alternately, log files can be rotated at fixed time intervals by specifying a value oftime
. - Overridable
- false
logging.audit.rotation.limit
- Default
- Description
- If you've set
logging.audit.rotation.type=size
you can specify the size limit in bytes to determine the rotation frequency of the audit log. Example:1000000
. The file that exceeds the limit will be renamed with a unique suffix and all the subsequent entries will be added to the newly created file. - Overridable
- false
logging.audit.rotation.interval
- Default
- Description
- If you've set
logging.audit.rotation.type=time
you can specify the log to be rotated at fixed time intervals. The interval value should be a positive integer followed by either letter 'd' (for days) or letter 'h' (for hours). Examples intervals are7d
for weekly logs,1d
for daily logs,12h
for two log files per day, and1h
for hourly logs. The file that exceeds the interval will be renamed with a unique suffix and all the subsequent entries will be added to the newly created file - Overridable
- false
logging.audit.rotation.compress
- Default
false
- Description
- When rotation is enabled setting this options to
true
will cause rotated log files to be compressed with gzip. - Overridable
- false
logging.audit.rotation.file.count
- Default
-1
- Description
- The maximum number of rotated files to keep. When the number of rotated files exceed this limit the oldest rotated file will be deleted. Setting this option to
-1
means the limit is undefined and all rotated files will be kept indefinitely. If the option is set to0
then no rotated files will be kept. Once the log file reaches the rotation limit it will be deleted and a fresh log file will be created. - Overridable
- false
Slow Query Logging
The server properties used for Slow Query Logging are listed below:
logging.slow_query.enabled
- Default
false
- Description
- Slow query logging is disabled by default and should be enabled explicitly by setting this to
true
- Overridable
- false
logging.slow_query.time
- Default
false
- Description
- To define what counts as a "slow" query, set this property to a time duration value (positive integer plus
h
,m
,s
, orms
for hours, minutes, seconds, or milliseconds respectively). - Overridable
- false
logging.slow_query.type
- Default
text
- Description
- Log type. Unlike access or audit logs, slow query log has a default type for formatting the slow query events which is intended to be human-readable. If no log type is specified, this default type (
text
) will be used. This default format is not suitable for machine-processing and meant to be only for developers to read. For a machine-processable format, the type of the slow query log can be set similar to access and audit logs,binary
. - Overridable
- false
Monitoring
Properties used to configure Server Monitoring:
metrics.reporter
- Default
- Description
- Enables JMX monitoring by setting this property to a value of
jmx
- Overridable
- false
metrics.jmx.remote.access
- Default
false
- Description
- When set to
true
, Stardog will bind an RMI server for remote access on port5833
to connect to the JMX server remotely. To change the port, modify themetrics.jmx.port
server property. - Overridable
- false
metrics.jmx.port
- Default
5833
- Description
- The port Stardog will expose for a JMX server to connect to remotely.
- Overridable
- false
Exports
export.dir
- Default
$STARDOG_HOME/.exports
- Description
- The top-level directory for storing files which are exported by the server. The default value is
.exports
in your$STARDOG_HOME
directory. - Overridable
- false
HTTP Configuration
http.max.connection
- Default
200
- Description
- The maximum number of simultaneous http connections.
- Overridable
- false
http.max.get.query.length
- Default
2000
- Description
- The length in characters of the longest query that can be sent over HTTP GET to the Stardog server. This is to avoid URL overflow in some web servers. When the query is longer than this threshold, Stardog will automatically switch over to using HTTP POST.
- Overridable
- false
http.max.request.parameters
- Default
2000
- Description
- Any value smaller than Java's
Integer.MAX_VALUE
may be provided. Useful if you have lots of named graphs and are at risk of blowing out the default value. - Overridable
- false
cors.allowed.origins
- Default
- Description
- By default, CORS is enabled on Stardog's HTTP server (it can be disabled when starting the server via the CLI by including the
--no-cors
flag). In order for any cross-origin requests to be acknowledged, their Origin header value must be included in this list. Example:http://stardog.com, http://example.org
- Overridable
- false