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.properties
1. Example
Updatable Properties
Configuration Options

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.

Undesirable behavior will occur if this part of the filesystem runs out of (or even is low on) free disk space. Stardog will delete temporary files when they’re no longer needed. Still, 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. When using the Stardog HA Cluster, this is also true of Zookeeper’s access to free disk space.

`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 server properties (updatable and otherwise).

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 or FROM NAMED keywords, this option will define what data it is evaluated against; if true, it will run over the default graph and the union of all named graphs; if false (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. This value is 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. This value is 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. This can close 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

`query.memory.limit.hard`

Default: 9223372036854775807B
Description: Configuration option for determining the memory limit used by query. Value should be provided in bytes as seen in the default value. This value overrides lower database configurations.
Overridable: false

`query.memory.exceeds.strategy.hard`

Default: SPILL_TO_DISK
Description: Configuration option for determining strategy for the query behaviour once query memory limit reached. Specifying FINISH_QUERY_EXECUTION will override database configurations. Query memory limit is determined by the server configuration option query.memory.limit.
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. The superuser 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" (these are the default credentials used by the server start CLI command). For a secure installation of Stardog cluster, you should change these credentials by specifying this property and restarting 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

`password.store.sha1`

Default: true
Description: Sets whether to store SHA1-hashed credentials, required for MySQL Native Authentication
Overridable: false

`security.named.graphs`

Default: false
Description: Sets named graph security globally.
Overridable: true

`security.disable.password`

Default: false
Description: Sets whether username/password authentication is disabled. Default value changes to `true` in conjunction with Kerberos.
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. After that, the standard JVM locations within $JAVA_HOME are checked. 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 three allowed values: text, binary, and json. Both are based on Protobuf. In text 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. In binary 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, the 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 of time.
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 are 7d for weekly logs, 1d for daily logs, 12h for two log files per day, and 1h 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.access.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.access.rotation.file.count`

Default: -1
Description: The maximum number of rotated files to keep. When the number of rotated files exceeds 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 to 0, 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

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 three allowed values: text, binary, and json. Both are based on Protobuf. In text 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. In binary 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 of time.
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 are 7d for weekly logs, 1d for daily logs, 12h for two log files per day, and 1h 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 exceeds 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 to 0, 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.file`

Default: ${STARDOG_HOME}/slow_query.log
Description: File name for the slow query log. By default, slow query log is saved as a file named slow_query.log inside the ${STARDOG_HOME} directory. Optionally an absolute path can be provided to save the file in a different directory.
Overridable: false

`logging.slow_query.time`

Default: 1m
Description: To define what counts as a "slow" query, set this property to a time duration value (positive integer plus h, m, s, or ms 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 is meant only for developers to read. For a machine-processable format, the type of the slow query log can be set to binary, similar to access and audit logs.
Overridable: false

`logging.slow_query.rotation.type`

Default
Description: It is possible to define a file rotation strategy so that slow query 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 of time.
Overridable: false

`logging.slow_query.rotation.limit`

Default
Description: If you've set logging.slow_query.rotation.type=size, you can specify the size limit in bytes to determine the rotation frequency of the slow query 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.slow_query.rotation.interval`

Default
Description: If you've set logging.slow_query.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 are 7d for weekly logs, 1d for daily logs, 12h for two log files per day, and 1h 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.slow_query.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.slow_query.rotation.file.count`

Default: -1
Description: The maximum number of rotated files to keep. When the number of rotated files exceeds 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 to 0, 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

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 port 5833 to connect to the JMX server remotely. To change the port, modify the metrics.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 exceeding 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

Optimizer Configuration

`optimizer.join.order.robustness`

Default: true
Description: When enabled, the query plan optimizer will consider alternative join orders in the presence of SPARQL-based services and select a *robust* query plan. See this section for more details. The behaviour can also be disabled on a per-query basis using the optimizer.join.order.topk query hint.
Overridable: false

System Database Checkpoints

`storage.checkpoint.system.interval.minutes`

Default: 360
Description: When non-zero, Stardog automatically creates a checkpoint of the system database every XX minutes. Checkpoints provide a quick backup of the Stardog's internal management data. See <a href="../database-administration/checkpoint> this section</a> for more details.
Overridable: false

`storage.checkpoint.system.intervals.keep`

Default: 3
Description: When non-zero, Stardog automatically removes older interval checkpoints, keeping the most recent XX checkpoints.
Overridable: false

`storage.checkpoint.system.days.keep`

Default: 3
Description: When non-zero, Stardog automatically keeps the last interval checkpoint of each day for the last XX days. Stardog will remove checkpoints older than XX days.
Overridable: false

`storage.checkpoint.system.weeks.keep`

Default: 2
Description: When non-zero, Stardog automatically keeps the last interval checkpoint of each week for the last XX weeks. Typically this is the last interval checkpoint on Sunday. Stardog will remove checkpoints older than XX weeks.
Overridable: false

Database Optimize

`storage.overload.optimize.threads`

Default: false
Description: Database optimize is very cpu and disk resource intensive. Stardog's default configuration is to intentionally throttle the optimize operation. The throttling ensures that queries executing simultaneously are not severely impacted. Setting this option to true disables the intentional throttling. An example use is when database optimize is known to execute at night when user queries do not occur.
Overridable: false

Network Connection Keepalive

`stardog.keep.alive.enabled`

Default: true
Description: Keepalive is a network feature supplied by the operating system. The feature requires that Stardog request the keepalive support for each network connection from client/user applications. Stardog does this by default since version 10.2. Keepalive is especially helpful to long processing requests, such as database optimize, when those requests cross routers/gateways that exist between the client and Stardog. Setting this option to false disables the feature.
Overridable: false

Keepalive often needs tuning at the operating system level to address specific network conditions. By default, the operating system only initiates keepalive after 2 hours. Yet network routers might terminate dormant network connections after as little as 4 minutes. Details on how to configure keepalive can be found here. Similar web pages discussing specific installations, such as kubernetes, exist and are easily found via web search engines.